0163b0824f2d038604eac67eedc64fd9135d1cec
[people/lynusvaz/gpxe.git] / src / include / gpxe / image.h
1 #ifndef _GPXE_IMAGE_H
2 #define _GPXE_IMAGE_H
3
4 /**
5  * @file
6  *
7  * Executable/loadable images
8  *
9  */
10
11 #include <gpxe/tables.h>
12 #include <gpxe/list.h>
13 #include <gpxe/uaccess.h>
14 #include <gpxe/refcnt.h>
15
16 struct uri;
17 struct image_type;
18
19 /** An executable or loadable image */
20 struct image {
21         /** Reference count */
22         struct refcnt refcnt;
23
24         /** List of registered images */
25         struct list_head list;
26
27         /** URI of image */
28         struct uri *uri;
29         /** Name */
30         char name[16];
31         /** Flags */
32         unsigned int flags;
33
34         /** Command line to pass to image */
35         char *cmdline;
36         /** Raw file image */
37         userptr_t data;
38         /** Length of raw file image */
39         size_t len;
40
41         /** Image type, if known */
42         struct image_type *type;
43         /** Image type private data */
44         union {
45                 physaddr_t phys;
46                 userptr_t user;
47                 unsigned long ul;
48         } priv;
49
50         /** Replacement image
51          *
52          * An image wishing to replace itself with another image (in a
53          * style similar to a Unix exec() call) should return from its
54          * exec() method with the replacement image set to point to
55          * the new image.  The new image must already be in a suitable
56          * state for execution.
57          */
58         struct image *replacement;
59 };
60
61 /** Image is loaded */
62 #define IMAGE_LOADED 0x0001
63
64 /** An executable or loadable image type */
65 struct image_type {
66         /** Name of this image type */
67         char *name;
68         /**
69          * Load image into memory
70          *
71          * @v image             Executable/loadable image
72          * @ret rc              Return status code
73          *
74          * Load the image into memory at the correct location as
75          * determined by the file format.
76          *
77          * If the file image is in the correct format, the method must
78          * update @c image->type to point to its own type (unless @c
79          * image->type is already set).  This allows the autoloading
80          * code to disambiguate between "this is not my image format"
81          * and "there is something wrong with this image".  In
82          * particular, setting @c image->type and then returning an
83          * error will cause image_autoload() to abort and return an
84          * error, rather than continuing to the next image type.
85          */
86         int ( * load ) ( struct image *image );
87         /**
88          * Execute loaded image
89          *
90          * @v image             Loaded image
91          * @ret rc              Return status code
92          *
93          * Note that the image may be invalidated by the act of
94          * execution, i.e. an image is allowed to choose to unregister
95          * (and so potentially free) itself.
96          */
97         int ( * exec ) ( struct image *image );
98 };
99
100 /**
101  * Multiboot image probe priority
102  *
103  * Multiboot images are also valid executables in another format
104  * (e.g. ELF), so we must perform the multiboot probe first.
105  */
106 #define PROBE_MULTIBOOT 01
107
108 /**
109  * Normal image probe priority
110  */
111 #define PROBE_NORMAL 02
112
113 /**
114  * PXE image probe priority
115  *
116  * PXE images have no signature checks, so will claim all image files.
117  * They must therefore be tried last in the probe order list.
118  */
119 #define PROBE_PXE 03
120
121 /** An executable or loadable image type */
122 #define __image_type( probe_order ) \
123          __table ( struct image_type, image_types, probe_order )
124
125 extern struct list_head images;
126
127 /** Iterate over all registered images */
128 #define for_each_image( image ) \
129         list_for_each_entry ( (image), &images, list )
130
131 extern struct image * alloc_image ( void );
132 extern int image_set_uri ( struct image *image, struct uri *uri );
133 extern int image_set_cmdline ( struct image *image, const char *cmdline );
134 extern int register_image ( struct image *image );
135 extern void unregister_image ( struct image *image );
136 extern void promote_image ( struct image *image );
137 struct image * find_image ( const char *name );
138 extern int image_load ( struct image *image );
139 extern int image_autoload ( struct image *image );
140 extern int image_exec ( struct image *image );
141 extern int register_and_autoload_image ( struct image *image );
142 extern int register_and_autoexec_image ( struct image *image );
143
144 /**
145  * Increment reference count on an image
146  *
147  * @v image             Image
148  * @ret image           Image
149  */
150 static inline struct image * image_get ( struct image *image ) {
151         ref_get ( &image->refcnt );
152         return image;
153 }
154
155 /**
156  * Decrement reference count on an image
157  *
158  * @v image             Image
159  */
160 static inline void image_put ( struct image *image ) {
161         ref_put ( &image->refcnt );
162 }
163
164 /**
165  * Set image name
166  *
167  * @v image             Image
168  * @v name              New image name
169  * @ret rc              Return status code
170  */
171 static inline int image_set_name ( struct image *image, const char *name ) {
172         strncpy ( image->name, name, ( sizeof ( image->name ) - 1 ) );
173         return 0;
174 }
175
176 #endif /* _GPXE_IMAGE_H */