src/include/gpxe/image.h

   1 #ifndef _GPXE_IMAGE_H
   2 #define _GPXE_IMAGE_H
   3
   4 /**
   5  * @file
   6  *
   7  * Executable/loadable images
   8  *
   9  */
  10
  11 #include <gpxe/tables.h>
  12 #include <gpxe/list.h>
  13 #include <gpxe/uaccess.h>
  14 #include <gpxe/refcnt.h>
  15
  16 struct uri;
  17 struct image_type;
  18
  19 /** An executable or loadable image */
  20 struct image {
  21         /** Reference count */
  22         struct refcnt refcnt;
  23
  24         /** List of registered images */
  25         struct list_head list;
  26
  27         /** URI of image */
  28         struct uri *uri;
  29         /** Name */
  30         char name[16];
  31         /** Flags */
  32         unsigned int flags;
  33
  34         /** Command line to pass to image */
  35         char *cmdline;
  36         /** Raw file image */
  37         userptr_t data;
  38         /** Length of raw file image */
  39         size_t len;
  40
  41         /** Image type, if known */
  42         struct image_type *type;
  43         /** Image type private data */
  44         union {
  45                 physaddr_t phys;
  46                 userptr_t user;
  47                 unsigned long ul;
  48         } priv;
  49
  50         /** Replacement image
  51          *
  52          * An image wishing to replace itself with another image (in a
  53          * style similar to a Unix exec() call) should return from its
  54          * exec() method with the replacement image set to point to
  55          * the new image.  The new image must already be in a suitable
  56          * state for execution (i.e. loaded).
  57          *
  58          * If an image unregisters itself as a result of being
  59          * executed, it must make sure that its replacement image (if
  60          * any) is registered, otherwise the replacement is likely to
  61          * be freed before it can be executed.
  62          */
  63         struct image *replacement;
  64 };
  65
  66 /** Image is loaded */
  67 #define IMAGE_LOADED 0x0001
  68
  69 /** An executable or loadable image type */
  70 struct image_type {
  71         /** Name of this image type */
  72         char *name;
  73         /**
  74          * Load image into memory
  75          *
  76          * @v image             Executable/loadable image
  77          * @ret rc              Return status code
  78          *
  79          * Load the image into memory at the correct location as
  80          * determined by the file format.
  81          *
  82          * If the file image is in the correct format, the method must
  83          * update @c image->type to point to its own type (unless @c
  84          * image->type is already set).  This allows the autoloading
  85          * code to disambiguate between "this is not my image format"
  86          * and "there is something wrong with this image".  In
  87          * particular, setting @c image->type and then returning an
  88          * error will cause image_autoload() to abort and return an
  89          * error, rather than continuing to the next image type.
  90          */
  91         int ( * load ) ( struct image *image );
  92         /**
  93          * Execute loaded image
  94          *
  95          * @v image             Loaded image
  96          * @ret rc              Return status code
  97          *
  98          * Note that the image may be invalidated by the act of
  99          * execution, i.e. an image is allowed to choose to unregister
 100          * (and so potentially free) itself.
 101          */
 102         int ( * exec ) ( struct image *image );
 103 };
 104
 105 /**
 106  * Multiboot image probe priority
 107  *
 108  * Multiboot images are also valid executables in another format
 109  * (e.g. ELF), so we must perform the multiboot probe first.
 110  */
 111 #define PROBE_MULTIBOOT 01
 112
 113 /**
 114  * Normal image probe priority
 115  */
 116 #define PROBE_NORMAL 02
 117
 118 /**
 119  * PXE image probe priority
 120  *
 121  * PXE images have no signature checks, so will claim all image files.
 122  * They must therefore be tried last in the probe order list.
 123  */
 124 #define PROBE_PXE 03
 125
 126 /** Executable or loadable image type table */
 127 #define IMAGE_TYPES __table ( struct image_type, "image_types" )
 128
 129 /** An executable or loadable image type */
 130 #define __image_type( probe_order ) __table_entry ( IMAGE_TYPES, probe_order )
 131
 132 extern struct list_head images;
 133
 134 /** Iterate over all registered images */
 135 #define for_each_image( image ) \
 136         list_for_each_entry ( (image), &images, list )
 137
 138 /**
 139  * Test for existence of images
 140  *
 141  * @ret existence       Some images exist
 142  */
 143 static inline int have_images ( void ) {
 144         return ( ! list_empty ( &images ) );
 145 }
 146
 147 extern struct image * alloc_image ( void );
 148 extern int image_set_uri ( struct image *image, struct uri *uri );
 149 extern int image_set_cmdline ( struct image *image, const char *cmdline );
 150 extern int register_image ( struct image *image );
 151 extern void unregister_image ( struct image *image );
 152 extern void promote_image ( struct image *image );
 153 struct image * find_image ( const char *name );
 154 extern int image_load ( struct image *image );
 155 extern int image_autoload ( struct image *image );
 156 extern int image_exec ( struct image *image );
 157 extern int register_and_autoload_image ( struct image *image );
 158 extern int register_and_autoexec_image ( struct image *image );
 159
 160 /**
 161  * Increment reference count on an image
 162  *
 163  * @v image             Image
 164  * @ret image           Image
 165  */
 166 static inline struct image * image_get ( struct image *image ) {
 167         ref_get ( &image->refcnt );
 168         return image;
 169 }
 170
 171 /**
 172  * Decrement reference count on an image
 173  *
 174  * @v image             Image
 175  */
 176 static inline void image_put ( struct image *image ) {
 177         ref_put ( &image->refcnt );
 178 }
 179
 180 /**
 181  * Set image name
 182  *
 183  * @v image             Image
 184  * @v name              New image name
 185  * @ret rc              Return status code
 186  */
 187 static inline int image_set_name ( struct image *image, const char *name ) {
 188         strncpy ( image->name, name, ( sizeof ( image->name ) - 1 ) );
 189         return 0;
 190 }
 191
 192 #endif /* _GPXE_IMAGE_H */