qemu/roms/ipxe/src/include/ipxe/image.h

   1 #ifndef _IPXE_IMAGE_H
   2 #define _IPXE_IMAGE_H
   3
   4 /**
   5  * @file
   6  *
   7  * Executable images
   8  *
   9  */
  10
  11 FILE_LICENCE ( GPL2_OR_LATER );
  12
  13 #include <ipxe/tables.h>
  14 #include <ipxe/list.h>
  15 #include <ipxe/uaccess.h>
  16 #include <ipxe/refcnt.h>
  17
  18 struct uri;
  19 struct pixel_buffer;
  20 struct image_type;
  21
  22 /** An executable image */
  23 struct image {
  24         /** Reference count */
  25         struct refcnt refcnt;
  26
  27         /** List of registered images */
  28         struct list_head list;
  29
  30         /** URI of image */
  31         struct uri *uri;
  32         /** Name */
  33         char *name;
  34         /** Flags */
  35         unsigned int flags;
  36
  37         /** Command line to pass to image */
  38         char *cmdline;
  39         /** Raw file image */
  40         userptr_t data;
  41         /** Length of raw file image */
  42         size_t len;
  43
  44         /** Image type, if known */
  45         struct image_type *type;
  46
  47         /** Replacement image
  48          *
  49          * An image wishing to replace itself with another image (in a
  50          * style similar to a Unix exec() call) should return from its
  51          * exec() method with the replacement image set to point to
  52          * the new image.
  53          *
  54          * If an image unregisters itself as a result of being
  55          * executed, it must make sure that its replacement image (if
  56          * any) is registered, otherwise the replacement is likely to
  57          * be freed before it can be executed.
  58          */
  59         struct image *replacement;
  60 };
  61
  62 /** Image is registered */
  63 #define IMAGE_REGISTERED 0x00001
  64
  65 /** Image is selected for execution */
  66 #define IMAGE_SELECTED 0x0002
  67
  68 /** Image is trusted */
  69 #define IMAGE_TRUSTED 0x0004
  70
  71 /** Image will be automatically unregistered after execution */
  72 #define IMAGE_AUTO_UNREGISTER 0x0008
  73
  74 /** An executable image type */
  75 struct image_type {
  76         /** Name of this image type */
  77         char *name;
  78         /**
  79          * Probe image
  80          *
  81          * @v image             Image
  82          * @ret rc              Return status code
  83          *
  84          * Return success if the image is of this image type.
  85          */
  86         int ( * probe ) ( struct image *image );
  87         /**
  88          * Execute image
  89          *
  90          * @v image             Image
  91          * @ret rc              Return status code
  92          */
  93         int ( * exec ) ( struct image *image );
  94         /**
  95          * Create pixel buffer from image
  96          *
  97          * @v image             Image
  98          * @v pixbuf            Pixel buffer to fill in
  99          * @ret rc              Return status code
 100          */
 101         int ( * pixbuf ) ( struct image *image, struct pixel_buffer **pixbuf );
 102 };
 103
 104 /**
 105  * Multiboot image probe priority
 106  *
 107  * Multiboot images are also valid executables in another format
 108  * (e.g. ELF), so we must perform the multiboot probe first.
 109  */
 110 #define PROBE_MULTIBOOT 01
 111
 112 /**
 113  * Normal image probe priority
 114  */
 115 #define PROBE_NORMAL 02
 116
 117 /**
 118  * PXE image probe priority
 119  *
 120  * PXE images have no signature checks, so will claim all image files.
 121  * They must therefore be tried last in the probe order list.
 122  */
 123 #define PROBE_PXE 03
 124
 125 /** Executable image type table */
 126 #define IMAGE_TYPES __table ( struct image_type, "image_types" )
 127
 128 /** An executable image type */
 129 #define __image_type( probe_order ) __table_entry ( IMAGE_TYPES, probe_order )
 130
 131 extern struct list_head images;
 132 extern struct image *current_image;
 133
 134 /** Iterate over all registered images */
 135 #define for_each_image( image ) \
 136         list_for_each_entry ( (image), &images, list )
 137
 138 /** Iterate over all registered images, safe against deletion */
 139 #define for_each_image_safe( image, tmp ) \
 140         list_for_each_entry_safe ( (image), (tmp), &images, list )
 141
 142 /**
 143  * Test for existence of images
 144  *
 145  * @ret existence       Some images exist
 146  */
 147 static inline int have_images ( void ) {
 148         return ( ! list_empty ( &images ) );
 149 }
 150
 151 /**
 152  * Retrieve first image
 153  *
 154  * @ret image           Image, or NULL
 155  */
 156 static inline struct image * first_image ( void ) {
 157         return list_first_entry ( &images, struct image, list );
 158 }
 159
 160 extern struct image * alloc_image ( struct uri *uri );
 161 extern int image_set_name ( struct image *image, const char *name );
 162 extern int image_set_cmdline ( struct image *image, const char *cmdline );
 163 extern int register_image ( struct image *image );
 164 extern void unregister_image ( struct image *image );
 165 struct image * find_image ( const char *name );
 166 extern int image_probe ( struct image *image );
 167 extern int image_exec ( struct image *image );
 168 extern int image_replace ( struct image *replacement );
 169 extern int image_select ( struct image *image );
 170 extern struct image * image_find_selected ( void );
 171 extern int image_set_trust ( int require_trusted, int permanent );
 172 extern int image_pixbuf ( struct image *image, struct pixel_buffer **pixbuf );
 173
 174 /**
 175  * Increment reference count on an image
 176  *
 177  * @v image             Image
 178  * @ret image           Image
 179  */
 180 static inline struct image * image_get ( struct image *image ) {
 181         ref_get ( &image->refcnt );
 182         return image;
 183 }
 184
 185 /**
 186  * Decrement reference count on an image
 187  *
 188  * @v image             Image
 189  */
 190 static inline void image_put ( struct image *image ) {
 191         ref_put ( &image->refcnt );
 192 }
 193
 194 /**
 195  * Clear image command line
 196  *
 197  * @v image             Image
 198  */
 199 static inline void image_clear_cmdline ( struct image *image ) {
 200         image_set_cmdline ( image, NULL );
 201 }
 202
 203 /**
 204  * Set image as trusted
 205  *
 206  * @v image             Image
 207  */
 208 static inline void image_trust ( struct image *image ) {
 209         image->flags |= IMAGE_TRUSTED;
 210 }
 211
 212 /**
 213  * Set image as untrusted
 214  *
 215  * @v image             Image
 216  */
 217 static inline void image_untrust ( struct image *image ) {
 218         image->flags &= ~IMAGE_TRUSTED;
 219 }
 220
 221 #endif /* _IPXE_IMAGE_H */