[comboot] Fix reference counting on replacement images
[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 (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 /** An executable or loadable image type */
127 #define __image_type( probe_order ) \
128          __table ( struct image_type, image_types, probe_order )
129
130 extern struct list_head images;
131
132 /** Iterate over all registered images */
133 #define for_each_image( image ) \
134         list_for_each_entry ( (image), &images, list )
135
136 extern struct image * alloc_image ( void );
137 extern int image_set_uri ( struct image *image, struct uri *uri );
138 extern int image_set_cmdline ( struct image *image, const char *cmdline );
139 extern int register_image ( struct image *image );
140 extern void unregister_image ( struct image *image );
141 extern void promote_image ( struct image *image );
142 struct image * find_image ( const char *name );
143 extern int image_load ( struct image *image );
144 extern int image_autoload ( struct image *image );
145 extern int image_exec ( struct image *image );
146 extern int register_and_autoload_image ( struct image *image );
147 extern int register_and_autoexec_image ( struct image *image );
148
149 /**
150  * Increment reference count on an image
151  *
152  * @v image             Image
153  * @ret image           Image
154  */
155 static inline struct image * image_get ( struct image *image ) {
156         ref_get ( &image->refcnt );
157         return image;
158 }
159
160 /**
161  * Decrement reference count on an image
162  *
163  * @v image             Image
164  */
165 static inline void image_put ( struct image *image ) {
166         ref_put ( &image->refcnt );
167 }
168
169 /**
170  * Set image name
171  *
172  * @v image             Image
173  * @v name              New image name
174  * @ret rc              Return status code
175  */
176 static inline int image_set_name ( struct image *image, const char *name ) {
177         strncpy ( image->name, name, ( sizeof ( image->name ) - 1 ) );
178         return 0;
179 }
180
181 #endif /* _GPXE_IMAGE_H */