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 0x0001
65 
66 /** Image is trusted */
67 #define IMAGE_TRUSTED 0x0002
68 
69 /** Image will be automatically unregistered after execution */
70 #define IMAGE_AUTO_UNREGISTER 0x0004
71 
72 /** Image will be hidden from enumeration */
73 #define IMAGE_HIDDEN 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  * Extract archive image
118  *
119  * @v image Image
120  * @v extracted Extracted image
121  * @ret rc Return status code
122  */
123  int ( * extract ) ( struct image *image, struct image *extracted );
124 };
125 
126 /**
127  * Multiboot image probe priority
128  *
129  * Multiboot images are also valid executables in another format
130  * (e.g. ELF), so we must perform the multiboot probe first.
131  */
132 #define PROBE_MULTIBOOT 01
133 
134 /**
135  * Normal image probe priority
136  */
137 #define PROBE_NORMAL 02
138 
139 /**
140  * PXE image probe priority
141  *
142  * PXE images have no signature checks, so will claim all image files.
143  * They must therefore be tried last in the probe order list.
144  */
145 #define PROBE_PXE 03
146 
147 /** Executable image type table */
148 #define IMAGE_TYPES __table ( struct image_type, "image_types" )
149 
150 /** An executable image type */
151 #define __image_type( probe_order ) __table_entry ( IMAGE_TYPES, probe_order )
152 
153 /** An image tag */
154 struct image_tag {
155  /** Name */
156  const char *name;
157  /** Image (weak reference, nullified when image is freed) */
158  struct image *image;
159 };
160 
161 /** Image tag table */
162 #define IMAGE_TAGS __table ( struct image_tag, "image_tags" )
163 
164 /** An image tag */
165 #define __image_tag __table_entry ( IMAGE_TAGS, 01 )
166 
167 extern struct list_head images;
168 extern struct image_tag current_image;
169 extern struct image_tag selected_image;
170 
171 /** Iterate over all registered images */
172 #define for_each_image( image ) \
173  list_for_each_entry ( (image), &images, list )
174 
175 /** Iterate over all registered images, safe against deletion */
176 #define for_each_image_safe( image, tmp ) \
177  list_for_each_entry_safe ( (image), (tmp), &images, list )
178 
179 /**
180  * Retrieve first image
181  *
182  * @ret image Image, or NULL
183  */
184 static inline struct image * first_image ( void ) {
185  return list_first_entry ( &images, struct image, list );
186 }
187 
188 extern struct image * alloc_image ( struct uri *uri );
189 extern int image_set_uri ( struct image *image, struct uri *uri );
190 extern int image_set_name ( struct image *image, const char *name );
191 extern char * image_strip_suffix ( struct image *image );
192 extern int image_set_cmdline ( struct image *image, const char *cmdline );
193 extern int image_set_len ( struct image *image, size_t len );
194 extern int image_set_data ( struct image *image, userptr_t data, size_t len );
195 extern int register_image ( struct image *image );
196 extern void unregister_image ( struct image *image );
197 extern struct image * find_image ( const char *name );
198 extern struct image * find_image_tag ( struct image_tag *tag );
199 extern int image_exec ( struct image *image );
200 extern int image_replace ( struct image *replacement );
201 extern int image_select ( struct image *image );
202 extern int image_set_trust ( int require_trusted, int permanent );
203 extern struct image * image_memory ( const char *name, userptr_t data,
204  size_t len );
205 extern const char * image_argument ( struct image *image, const char *key );
206 extern int image_pixbuf ( struct image *image, struct pixel_buffer **pixbuf );
207 extern int image_asn1 ( struct image *image, size_t offset,
208  struct asn1_cursor **cursor );
209 extern int image_extract ( struct image *image, const char *name,
210  struct image **extracted );
211 extern int image_extract_exec ( struct image *image );
212 
213 /**
214  * Increment reference count on an image
215  *
216  * @v image Image
217  * @ret image Image
218  */
219 static inline struct image * image_get ( struct image *image ) {
220  ref_get ( &image->refcnt );
221  return image;
222 }
223 
224 /**
225  * Decrement reference count on an image
226  *
227  * @v image Image
228  */
229 static inline void image_put ( struct image *image ) {
230  ref_put ( &image->refcnt );
231 }
232 
233 /**
234  * Clear image command line
235  *
236  * @v image Image
237  */
238 static inline void image_clear_cmdline ( struct image *image ) {
240 }
241 
242 /**
243  * Set image as trusted
244  *
245  * @v image Image
246  */
247 static inline void image_trust ( struct image *image ) {
249 }
250 
251 /**
252  * Set image as untrusted
253  *
254  * @v image Image
255  */
256 static inline void image_untrust ( struct image *image ) {
258 }
259 
260 /**
261  * Mark image as hidden
262  *
263  * @v image Image
264  */
265 static inline void image_hide ( struct image *image ) {
267 }
268 
269 /**
270  * Tag image
271  *
272  * @v image Image
273  * @v tag Image tag
274  * @ret prev Previous tagged image (if any)
275  */
276 static inline struct image * image_tag ( struct image *image,
277  struct image_tag *tag ) {
278  struct image *prev = tag->image;
279 
280  tag->image = image;
281  return prev;
282 }
283 
284 #endif /* _IPXE_IMAGE_H */
const char * image_argument(struct image *image, const char *key)
Find argument within image command line.
Definition: image.c:612
struct image_tag selected_image
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:201
An image tag.
Definition: image.h:154
struct image * find_image_tag(struct image_tag *tag)
Find image by tag.
Definition: image.c:357
int register_image(struct image *image)
Register executable image.
Definition: image.c:286
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:219
An executable image type.
Definition: image.h:76
int image_set_data(struct image *image, userptr_t data, size_t len)
Set image data.
Definition: image.c:241
An executable image.
Definition: image.h:24
struct image * image
Image (weak reference, nullified when image is freed)
Definition: image.h:158
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
int image_set_len(struct image *image, size_t len)
Set image length.
Definition: image.c:220
A reference counter.
Definition: refcnt.h:26
#define list_first_entry(list, type, member)
Get the container of the first entry in a list.
Definition: list.h:333
struct image_tag current_image
uint32_t userptr_t
A pointer to a user buffer.
Definition: libkir.h:159
const char * replacement
Definition: editstring.h:53
int image_asn1(struct image *image, size_t offset, struct asn1_cursor **cursor)
Extract ASN.1 object from image.
Definition: asn1.c:1002
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:132
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:322
struct image * alloc_image(struct uri *uri)
Allocate executable image.
Definition: image.c:103
static struct image * first_image(void)
Retrieve first image.
Definition: image.h:184
Linked lists.
struct image * find_image(const char *name)
Find image by name.
Definition: image.c:340
static void image_untrust(struct image *image)
Set image as untrusted.
Definition: image.h:256
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
char * image_strip_suffix(struct image *image)
Strip dot suffix from image name, if present.
Definition: image.c:181
A pixel buffer.
Definition: pixbuf.h:17
#define IMAGE_HIDDEN
Image will be hidden from enumeration.
Definition: image.h:73
#define IMAGE_TRUSTED
Image is trusted.
Definition: image.h:67
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:229
int(* extract)(struct image *image, struct image *extracted)
Extract archive image.
Definition: image.h:123
struct image * image_memory(const char *name, userptr_t data, size_t len)
Create registered image from block of memory.
Definition: image.c:569
int image_extract(struct image *image, const char *name, struct image **extracted)
Extract archive image.
Definition: archive.c:44
int image_extract_exec(struct image *image)
Extract and execute image.
Definition: archive.c:107
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
int image_set_trust(int require_trusted, int permanent)
Change image trust requirement.
Definition: image.c:544
static void image_clear_cmdline(struct image *image)
Clear image command line.
Definition: image.h:238
Reference counting.
uint8_t data[48]
Additional event data.
Definition: ena.h:22
struct image * replacement
Replacement image.
Definition: image.h:60
Linker tables.
int image_select(struct image *image)
Select image for execution.
Definition: image.c:525
int(* probe)(struct image *image)
Probe image.
Definition: image.h:87
A Uniform Resource Identifier.
Definition: uri.h:64
uint16_t offset
Offset to command line.
Definition: bzimage.h:8
static void image_trust(struct image *image)
Set image as trusted.
Definition: image.h:247
struct list_head list
List of registered images.
Definition: image.h:29
static struct image * image_tag(struct image *image, struct image_tag *tag)
Tag image.
Definition: image.h:276
uint32_t cmdline
Definition: multiboot.h:16
uint64_t tag
Identity tag.
Definition: edd.h:30
int image_exec(struct image *image)
Execute image.
Definition: image.c:378
char * name
Name.
Definition: image.h:34
uint32_t len
Length.
Definition: ena.h:14
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
const char * name
Name.
Definition: image.h:156
An ASN.1 object cursor.
Definition: asn1.h:20
union @383 key
Sense key.
Definition: scsi.h:18
int image_replace(struct image *replacement)
Set replacement image.
Definition: image.c:489
#define ref_put(refcnt)
Drop reference to object.
Definition: refcnt.h:106
struct list_head images
List of registered images.
Definition: image.c:57
static void image_hide(struct image *image)
Mark image as hidden.
Definition: image.h:265
int image_set_name(struct image *image, const char *name)
Set image name.
Definition: image.c:160
struct refcnt refcnt
Reference count.
Definition: image.h:26