iPXE
image.h
Go to the documentation of this file.
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_OR_UBDL );
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 asn1_cursor;
21 struct image_type;
22 
23 /** An executable image */
24 struct image {
25  /** Reference count */
26  struct refcnt refcnt;
27 
28  /** List of registered images */
29  struct list_head list;
30 
31  /** URI of image */
32  struct uri *uri;
33  /** Name */
34  char *name;
35  /** Flags */
36  unsigned int flags;
37 
38  /** Command line to pass to image */
39  char *cmdline;
40  /** Raw file image */
42  /** Length of raw file image */
43  size_t len;
44 
45  /** Image type, if known */
46  struct image_type *type;
47 
48  /** Replacement image
49  *
50  * An image wishing to replace itself with another image (in a
51  * style similar to a Unix exec() call) should return from its
52  * exec() method with the replacement image set to point to
53  * the new image.
54  *
55  * If an image unregisters itself as a result of being
56  * executed, it must make sure that its replacement image (if
57  * any) is registered, otherwise the replacement is likely to
58  * be freed before it can be executed.
59  */
60  struct image *replacement;
61 };
62 
63 /** Image is registered */
64 #define IMAGE_REGISTERED 0x00001
65 
66 /** Image is selected for execution */
67 #define IMAGE_SELECTED 0x0002
68 
69 /** Image is trusted */
70 #define IMAGE_TRUSTED 0x0004
71 
72 /** Image will be automatically unregistered after execution */
73 #define IMAGE_AUTO_UNREGISTER 0x0008
74 
75 /** An executable image type */
76 struct image_type {
77  /** Name of this image type */
78  char *name;
79  /**
80  * Probe image
81  *
82  * @v image Image
83  * @ret rc Return status code
84  *
85  * Return success if the image is of this image type.
86  */
87  int ( * probe ) ( struct image *image );
88  /**
89  * Execute image
90  *
91  * @v image Image
92  * @ret rc Return status code
93  */
94  int ( * exec ) ( struct image *image );
95  /**
96  * Create pixel buffer from image
97  *
98  * @v image Image
99  * @v pixbuf Pixel buffer to fill in
100  * @ret rc Return status code
101  */
102  int ( * pixbuf ) ( struct image *image, struct pixel_buffer **pixbuf );
103  /**
104  * Extract ASN.1 object from image
105  *
106  * @v image Image
107  * @v offset Offset within image
108  * @v cursor ASN.1 cursor to fill in
109  * @ret next Offset to next image, or negative error
110  *
111  * The caller is responsible for eventually calling free() on
112  * the allocated ASN.1 cursor.
113  */
114  int ( * asn1 ) ( struct image *image, size_t offset,
115  struct asn1_cursor **cursor );
116 };
117 
118 /**
119  * Multiboot image probe priority
120  *
121  * Multiboot images are also valid executables in another format
122  * (e.g. ELF), so we must perform the multiboot probe first.
123  */
124 #define PROBE_MULTIBOOT 01
125 
126 /**
127  * Normal image probe priority
128  */
129 #define PROBE_NORMAL 02
130 
131 /**
132  * PXE image probe priority
133  *
134  * PXE images have no signature checks, so will claim all image files.
135  * They must therefore be tried last in the probe order list.
136  */
137 #define PROBE_PXE 03
138 
139 /** Executable image type table */
140 #define IMAGE_TYPES __table ( struct image_type, "image_types" )
141 
142 /** An executable image type */
143 #define __image_type( probe_order ) __table_entry ( IMAGE_TYPES, probe_order )
144 
145 extern struct list_head images;
146 extern struct image *current_image;
147 
148 /** Iterate over all registered images */
149 #define for_each_image( image ) \
150  list_for_each_entry ( (image), &images, list )
151 
152 /** Iterate over all registered images, safe against deletion */
153 #define for_each_image_safe( image, tmp ) \
154  list_for_each_entry_safe ( (image), (tmp), &images, list )
155 
156 /**
157  * Test for existence of images
158  *
159  * @ret existence Some images exist
160  */
161 static inline int have_images ( void ) {
162  return ( ! list_empty ( &images ) );
163 }
164 
165 /**
166  * Retrieve first image
167  *
168  * @ret image Image, or NULL
169  */
170 static inline struct image * first_image ( void ) {
171  return list_first_entry ( &images, struct image, list );
172 }
173 
174 extern struct image * alloc_image ( struct uri *uri );
175 extern int image_set_uri ( struct image *image, struct uri *uri );
176 extern int image_set_name ( struct image *image, const char *name );
177 extern int image_set_cmdline ( struct image *image, const char *cmdline );
178 extern int register_image ( struct image *image );
179 extern void unregister_image ( struct image *image );
180 struct image * find_image ( const char *name );
181 extern int image_exec ( struct image *image );
182 extern int image_replace ( struct image *replacement );
183 extern int image_select ( struct image *image );
184 extern struct image * image_find_selected ( void );
185 extern int image_set_trust ( int require_trusted, int permanent );
186 extern int image_pixbuf ( struct image *image, struct pixel_buffer **pixbuf );
187 extern int image_asn1 ( struct image *image, size_t offset,
188  struct asn1_cursor **cursor );
189 
190 /**
191  * Increment reference count on an image
192  *
193  * @v image Image
194  * @ret image Image
195  */
196 static inline struct image * image_get ( struct image *image ) {
197  ref_get ( &image->refcnt );
198  return image;
199 }
200 
201 /**
202  * Decrement reference count on an image
203  *
204  * @v image Image
205  */
206 static inline void image_put ( struct image *image ) {
207  ref_put ( &image->refcnt );
208 }
209 
210 /**
211  * Clear image command line
212  *
213  * @v image Image
214  */
215 static inline void image_clear_cmdline ( struct image *image ) {
217 }
218 
219 /**
220  * Set image as trusted
221  *
222  * @v image Image
223  */
224 static inline void image_trust ( struct image *image ) {
226 }
227 
228 /**
229  * Set image as untrusted
230  *
231  * @v image Image
232  */
233 static inline void image_untrust ( struct image *image ) {
235 }
236 
237 #endif /* _IPXE_IMAGE_H */
unsigned int flags
Flags.
Definition: image.h:36
const char * name
Definition: ath9k_hw.c:1984
userptr_t data
Raw file image.
Definition: image.h:41
int image_set_cmdline(struct image *image, const char *cmdline)
Set image command line.
Definition: image.c:166
int register_image(struct image *image)
Register executable image.
Definition: image.c:210
struct image_type * type
Image type, if known.
Definition: image.h:46
static struct image * image_get(struct image *image)
Increment reference count on an image.
Definition: image.h:196
An executable image type.
Definition: image.h:76
An executable image.
Definition: image.h:24
Access to external ("user") memory.
int(* exec)(struct image *image)
Execute image.
Definition: image.h:94
char * name
Name of this image type.
Definition: image.h:78
char * cmdline
Command line to pass to image.
Definition: image.h:39
A doubly-linked list entry (or list head)
Definition: list.h:18
A reference counter.
Definition: refcnt.h:26
#define list_empty(list)
Test whether a list is empty.
Definition: list.h:136
#define list_first_entry(list, type, member)
Get the container of the first entry in a list.
Definition: list.h:333
int image_asn1(struct image *image, size_t offset, struct asn1_cursor **cursor)
Extract ASN.1 object from image.
Definition: asn1.c:854
static userptr_t size_t offset
Offset of the first segment within the content.
Definition: deflate.h:259
int(* asn1)(struct image *image, size_t offset, struct asn1_cursor **cursor)
Extract ASN.1 object from image.
Definition: image.h:114
int image_set_uri(struct image *image, struct uri *uri)
Set image URI.
Definition: image.c:119
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:252
struct image * alloc_image(struct uri *uri)
Allocate executable image.
Definition: image.c:90
static struct image * first_image(void)
Retrieve first image.
Definition: image.h:170
Linked lists.
struct image * find_image(const char *name)
Find image by name.
Definition: image.c:270
static void image_untrust(struct image *image)
Set image as untrusted.
Definition: image.h:233
size_t len
Length of raw file image.
Definition: image.h:43
#define ref_get(refcnt)
Get additional reference to object.
Definition: refcnt.h:92
A pixel buffer.
Definition: pixbuf.h:17
#define IMAGE_TRUSTED
Image is trusted.
Definition: image.h:70
struct uri * uri
URI of image.
Definition: image.h:32
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
static void image_put(struct image *image)
Decrement reference count on an image.
Definition: image.h:206
struct image * current_image
Currently-executing image.
Definition: image.c:59
int image_pixbuf(struct image *image, struct pixel_buffer **pixbuf)
Create pixel buffer from image.
Definition: pixbuf.c:97
int(* pixbuf)(struct image *image, struct pixel_buffer **pixbuf)
Create pixel buffer from image.
Definition: image.h:102
static int have_images(void)
Test for existence of images.
Definition: image.h:161
int image_set_trust(int require_trusted, int permanent)
Change image trust requirement.
Definition: image.c:468
static void image_clear_cmdline(struct image *image)
Clear image command line.
Definition: image.h:215
Reference counting.
struct image * replacement
Replacement image.
Definition: image.h:60
Linker tables.
int image_select(struct image *image)
Select image for execution.
Definition: image.c:429
int(* probe)(struct image *image)
Probe image.
Definition: image.h:87
A Uniform Resource Identifier.
Definition: uri.h:50
static void image_trust(struct image *image)
Set image as trusted.
Definition: image.h:224
struct list_head list
List of registered images.
Definition: image.h:29
uint32_t cmdline
Definition: multiboot.h:16
int image_exec(struct image *image)
Execute image.
Definition: image.c:291
char * name
Name.
Definition: image.h:34
struct image * image_find_selected(void)
Find selected image.
Definition: image.c:451
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
An ASN.1 object cursor.
Definition: asn1.h:19
int image_replace(struct image *replacement)
Set replacement image.
Definition: image.c:393
#define ref_put(refcnt)
Drop reference to object.
Definition: refcnt.h:106
unsigned long userptr_t
A pointer to a user buffer.
Definition: uaccess.h:33
struct list_head images
List of registered images.
Definition: image.c:56
int image_set_name(struct image *image, const char *name)
Set image name.
Definition: image.c:144
struct refcnt refcnt
Reference count.
Definition: image.h:26