iPXE
image.h
Go to the documentation of this file.
00001 #ifndef _IPXE_IMAGE_H
00002 #define _IPXE_IMAGE_H
00003 
00004 /**
00005  * @file
00006  *
00007  * Executable images
00008  *
00009  */
00010 
00011 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
00012 
00013 #include <ipxe/tables.h>
00014 #include <ipxe/list.h>
00015 #include <ipxe/uaccess.h>
00016 #include <ipxe/refcnt.h>
00017 
00018 struct uri;
00019 struct pixel_buffer;
00020 struct asn1_cursor;
00021 struct image_type;
00022 
00023 /** An executable image */
00024 struct image {
00025         /** Reference count */
00026         struct refcnt refcnt;
00027 
00028         /** List of registered images */
00029         struct list_head list;
00030 
00031         /** URI of image */
00032         struct uri *uri;
00033         /** Name */
00034         char *name;
00035         /** Flags */
00036         unsigned int flags;
00037 
00038         /** Command line to pass to image */
00039         char *cmdline;
00040         /** Raw file image */
00041         userptr_t data;
00042         /** Length of raw file image */
00043         size_t len;
00044 
00045         /** Image type, if known */
00046         struct image_type *type;
00047 
00048         /** Replacement image
00049          *
00050          * An image wishing to replace itself with another image (in a
00051          * style similar to a Unix exec() call) should return from its
00052          * exec() method with the replacement image set to point to
00053          * the new image.
00054          *
00055          * If an image unregisters itself as a result of being
00056          * executed, it must make sure that its replacement image (if
00057          * any) is registered, otherwise the replacement is likely to
00058          * be freed before it can be executed.
00059          */
00060         struct image *replacement;
00061 };
00062 
00063 /** Image is registered */
00064 #define IMAGE_REGISTERED 0x00001
00065 
00066 /** Image is selected for execution */
00067 #define IMAGE_SELECTED 0x0002
00068 
00069 /** Image is trusted */
00070 #define IMAGE_TRUSTED 0x0004
00071 
00072 /** Image will be automatically unregistered after execution */
00073 #define IMAGE_AUTO_UNREGISTER 0x0008
00074 
00075 /** An executable image type */
00076 struct image_type {
00077         /** Name of this image type */
00078         char *name;
00079         /**
00080          * Probe image
00081          *
00082          * @v image             Image
00083          * @ret rc              Return status code
00084          *
00085          * Return success if the image is of this image type.
00086          */
00087         int ( * probe ) ( struct image *image );
00088         /**
00089          * Execute image
00090          *
00091          * @v image             Image
00092          * @ret rc              Return status code
00093          */
00094         int ( * exec ) ( struct image *image );
00095         /**
00096          * Create pixel buffer from image
00097          *
00098          * @v image             Image
00099          * @v pixbuf            Pixel buffer to fill in
00100          * @ret rc              Return status code
00101          */
00102         int ( * pixbuf ) ( struct image *image, struct pixel_buffer **pixbuf );
00103         /**
00104          * Extract ASN.1 object from image
00105          *
00106          * @v image             Image
00107          * @v offset            Offset within image
00108          * @v cursor            ASN.1 cursor to fill in
00109          * @ret next            Offset to next image, or negative error
00110          *
00111          * The caller is responsible for eventually calling free() on
00112          * the allocated ASN.1 cursor.
00113          */
00114         int ( * asn1 ) ( struct image *image, size_t offset,
00115                          struct asn1_cursor **cursor );
00116 };
00117 
00118 /**
00119  * Multiboot image probe priority
00120  *
00121  * Multiboot images are also valid executables in another format
00122  * (e.g. ELF), so we must perform the multiboot probe first.
00123  */
00124 #define PROBE_MULTIBOOT 01
00125 
00126 /**
00127  * Normal image probe priority
00128  */
00129 #define PROBE_NORMAL 02
00130 
00131 /**
00132  * PXE image probe priority
00133  *
00134  * PXE images have no signature checks, so will claim all image files.
00135  * They must therefore be tried last in the probe order list.
00136  */
00137 #define PROBE_PXE 03
00138 
00139 /** Executable image type table */
00140 #define IMAGE_TYPES __table ( struct image_type, "image_types" )
00141 
00142 /** An executable image type */
00143 #define __image_type( probe_order ) __table_entry ( IMAGE_TYPES, probe_order )
00144 
00145 extern struct list_head images;
00146 extern struct image *current_image;
00147 
00148 /** Iterate over all registered images */
00149 #define for_each_image( image ) \
00150         list_for_each_entry ( (image), &images, list )
00151 
00152 /** Iterate over all registered images, safe against deletion */
00153 #define for_each_image_safe( image, tmp ) \
00154         list_for_each_entry_safe ( (image), (tmp), &images, list )
00155 
00156 /**
00157  * Test for existence of images
00158  *
00159  * @ret existence       Some images exist
00160  */
00161 static inline int have_images ( void ) {
00162         return ( ! list_empty ( &images ) );
00163 }
00164 
00165 /**
00166  * Retrieve first image
00167  *
00168  * @ret image           Image, or NULL
00169  */
00170 static inline struct image * first_image ( void ) {
00171         return list_first_entry ( &images, struct image, list );
00172 }
00173 
00174 extern struct image * alloc_image ( struct uri *uri );
00175 extern int image_set_uri ( struct image *image, struct uri *uri );
00176 extern int image_set_name ( struct image *image, const char *name );
00177 extern int image_set_cmdline ( struct image *image, const char *cmdline );
00178 extern int register_image ( struct image *image );
00179 extern void unregister_image ( struct image *image );
00180 struct image * find_image ( const char *name );
00181 extern int image_exec ( struct image *image );
00182 extern int image_replace ( struct image *replacement );
00183 extern int image_select ( struct image *image );
00184 extern struct image * image_find_selected ( void );
00185 extern int image_set_trust ( int require_trusted, int permanent );
00186 extern int image_pixbuf ( struct image *image, struct pixel_buffer **pixbuf );
00187 extern int image_asn1 ( struct image *image, size_t offset,
00188                         struct asn1_cursor **cursor );
00189 
00190 /**
00191  * Increment reference count on an image
00192  *
00193  * @v image             Image
00194  * @ret image           Image
00195  */
00196 static inline struct image * image_get ( struct image *image ) {
00197         ref_get ( &image->refcnt );
00198         return image;
00199 }
00200 
00201 /**
00202  * Decrement reference count on an image
00203  *
00204  * @v image             Image
00205  */
00206 static inline void image_put ( struct image *image ) {
00207         ref_put ( &image->refcnt );
00208 }
00209 
00210 /**
00211  * Clear image command line
00212  *
00213  * @v image             Image
00214  */
00215 static inline void image_clear_cmdline ( struct image *image ) {
00216         image_set_cmdline ( image, NULL );
00217 }
00218 
00219 /**
00220  * Set image as trusted
00221  *
00222  * @v image             Image
00223  */
00224 static inline void image_trust ( struct image *image ) {
00225         image->flags |= IMAGE_TRUSTED;
00226 }
00227 
00228 /**
00229  * Set image as untrusted
00230  *
00231  * @v image             Image
00232  */
00233 static inline void image_untrust ( struct image *image ) {
00234         image->flags &= ~IMAGE_TRUSTED;
00235 }
00236 
00237 #endif /* _IPXE_IMAGE_H */