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  * 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 extern struct list_head images;
154 extern struct image *current_image;
155 
156 /** Iterate over all registered images */
157 #define for_each_image( image ) \
158  list_for_each_entry ( (image), &images, list )
159 
160 /** Iterate over all registered images, safe against deletion */
161 #define for_each_image_safe( image, tmp ) \
162  list_for_each_entry_safe ( (image), (tmp), &images, list )
163 
164 /**
165  * Test for existence of images
166  *
167  * @ret existence Some images exist
168  */
169 static inline int have_images ( void ) {
170  return ( ! list_empty ( &images ) );
171 }
172 
173 /**
174  * Retrieve first image
175  *
176  * @ret image Image, or NULL
177  */
178 static inline struct image * first_image ( void ) {
179  return list_first_entry ( &images, struct image, list );
180 }
181 
182 extern struct image * alloc_image ( struct uri *uri );
183 extern int image_set_uri ( struct image *image, struct uri *uri );
184 extern int image_set_name ( struct image *image, const char *name );
185 extern int image_set_cmdline ( struct image *image, const char *cmdline );
186 extern int image_set_len ( struct image *image, size_t len );
187 extern int image_set_data ( struct image *image, userptr_t data, size_t len );
188 extern int register_image ( struct image *image );
189 extern void unregister_image ( struct image *image );
190 struct image * find_image ( const char *name );
191 extern int image_exec ( struct image *image );
192 extern int image_replace ( struct image *replacement );
193 extern int image_select ( struct image *image );
194 extern struct image * image_find_selected ( void );
195 extern int image_set_trust ( int require_trusted, int permanent );
196 extern struct image * image_memory ( const char *name, userptr_t data,
197  size_t len );
198 extern int image_pixbuf ( struct image *image, struct pixel_buffer **pixbuf );
199 extern int image_asn1 ( struct image *image, size_t offset,
200  struct asn1_cursor **cursor );
201 extern int image_extract ( struct image *image, const char *name,
202  struct image **extracted );
203 extern int image_extract_exec ( struct image *image );
204 
205 /**
206  * Increment reference count on an image
207  *
208  * @v image Image
209  * @ret image Image
210  */
211 static inline struct image * image_get ( struct image *image ) {
212  ref_get ( &image->refcnt );
213  return image;
214 }
215 
216 /**
217  * Decrement reference count on an image
218  *
219  * @v image Image
220  */
221 static inline void image_put ( struct image *image ) {
222  ref_put ( &image->refcnt );
223 }
224 
225 /**
226  * Clear image command line
227  *
228  * @v image Image
229  */
230 static inline void image_clear_cmdline ( struct image *image ) {
232 }
233 
234 /**
235  * Set image as trusted
236  *
237  * @v image Image
238  */
239 static inline void image_trust ( struct image *image ) {
241 }
242 
243 /**
244  * Set image as untrusted
245  *
246  * @v image Image
247  */
248 static inline void image_untrust ( struct image *image ) {
250 }
251 
252 #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:251
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:211
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:206
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
int image_set_len(struct image *image, size_t len)
Set image length.
Definition: image.c:185
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:293
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:178
Linked lists.
struct image * find_image(const char *name)
Find image by name.
Definition: image.c:311
static void image_untrust(struct image *image)
Set image as untrusted.
Definition: image.h:248
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:221
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:537
struct image * current_image
Currently-executing image.
Definition: image.c:59
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:110
int image_pixbuf(struct image *image, struct pixel_buffer **pixbuf)
Create pixel buffer from image.
Definition: pixbuf.c:97
uint32_t len
Length.
Definition: ena.h:14
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:169
int image_set_trust(int require_trusted, int permanent)
Change image trust requirement.
Definition: image.c:512
static void image_clear_cmdline(struct image *image)
Clear image command line.
Definition: image.h:230
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:473
int(* probe)(struct image *image)
Probe image.
Definition: image.h:87
A Uniform Resource Identifier.
Definition: uri.h:64
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12
static void image_trust(struct image *image)
Set image as trusted.
Definition: image.h:239
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:332
char * name
Name.
Definition: image.h:34
struct image * image_find_selected(void)
Find selected image.
Definition: image.c:495
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
An ASN.1 object cursor.
Definition: asn1.h:20
int image_replace(struct image *replacement)
Set replacement image.
Definition: image.c:437
#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