cb3bb361bf1b20548f53bbc08e92c812a0a108ef
[people/sha0/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 (i.e. loaded).
57          *
58          * If an image unregisters itself as a result of being
59          * executed, it must make sure that its replacement image (if
60          * any) is registered, otherwise the replacement is likely to
61          * be freed before it can be executed.
62          */
63         struct image *replacement;
64 };
65
66 /** Image is loaded */
67 #define IMAGE_LOADED 0x0001
68
69 /** An executable or loadable image type */
70 struct image_type {
71         /** Name of this image type */
72         char *name;
73         /**
74          * Load image into memory
75          *
76          * @v image             Executable/loadable image
77          * @ret rc              Return status code
78          *
79          * Load the image into memory at the correct location as
80          * determined by the file format.
81          *
82          * If the file image is in the correct format, the method must
83          * update @c image->type to point to its own type (unless @c
84          * image->type is already set).  This allows the autoloading
85          * code to disambiguate between "this is not my image format"
86          * and "there is something wrong with this image".  In
87          * particular, setting @c image->type and then returning an
88          * error will cause image_autoload() to abort and return an
89          * error, rather than continuing to the next image type.
90          */
91         int ( * load ) ( struct image *image );
92         /**
93          * Execute loaded image
94          *
95          * @v image             Loaded image
96          * @ret rc              Return status code
97          *
98          * Note that the image may be invalidated by the act of
99          * execution, i.e. an image is allowed to choose to unregister
100          * (and so potentially free) itself.
101          */
102         int ( * exec ) ( struct image *image );
103 };
104
105 /**
106  * Multiboot image probe priority
107  *
108  * Multiboot images are also valid executables in another format
109  * (e.g. ELF), so we must perform the multiboot probe first.
110  */
111 #define PROBE_MULTIBOOT 01
112
113 /**
114  * Normal image probe priority
115  */
116 #define PROBE_NORMAL 02
117
118 /**
119  * PXE image probe priority
120  *
121  * PXE images have no signature checks, so will claim all image files.
122  * They must therefore be tried last in the probe order list.
123  */
124 #define PROBE_PXE 03
125
126 /** Executable or loadable image type table */
127 #define IMAGE_TYPES "image_types"
128
129 /** An executable or loadable image type */
130 #define __image_type( probe_order ) \
131         __table ( struct image_type, IMAGE_TYPES, probe_order )
132
133 extern struct list_head images;
134
135 /** Iterate over all registered images */
136 #define for_each_image( image ) \
137         list_for_each_entry ( (image), &images, list )
138
139 /**
140  * Test for existence of images
141  *
142  * @ret existence       Some images exist
143  */
144 static inline int have_images ( void ) {
145         return ( ! list_empty ( &images ) );
146 }
147
148 extern struct image * alloc_image ( void );
149 extern int image_set_uri ( struct image *image, struct uri *uri );
150 extern int image_set_cmdline ( struct image *image, const char *cmdline );
151 extern int register_image ( struct image *image );
152 extern void unregister_image ( struct image *image );
153 extern void promote_image ( struct image *image );
154 struct image * find_image ( const char *name );
155 extern int image_load ( struct image *image );
156 extern int image_autoload ( struct image *image );
157 extern int image_exec ( struct image *image );
158 extern int register_and_autoload_image ( struct image *image );
159 extern int register_and_autoexec_image ( struct image *image );
160
161 /**
162  * Increment reference count on an image
163  *
164  * @v image             Image
165  * @ret image           Image
166  */
167 static inline struct image * image_get ( struct image *image ) {
168         ref_get ( &image->refcnt );
169         return image;
170 }
171
172 /**
173  * Decrement reference count on an image
174  *
175  * @v image             Image
176  */
177 static inline void image_put ( struct image *image ) {
178         ref_put ( &image->refcnt );
179 }
180
181 /**
182  * Set image name
183  *
184  * @v image             Image
185  * @v name              New image name
186  * @ret rc              Return status code
187  */
188 static inline int image_set_name ( struct image *image, const char *name ) {
189         strncpy ( image->name, name, ( sizeof ( image->name ) - 1 ) );
190         return 0;
191 }
192
193 #endif /* _GPXE_IMAGE_H */