iPXE
image.c
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2006 Michael Brown <mbrown@fensystems.co.uk>.
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License as
6  * published by the Free Software Foundation; either version 2 of the
7  * License, or any later version.
8  *
9  * This program is distributed in the hope that it will be useful, but
10  * WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17  * 02110-1301, USA.
18  *
19  * You can also choose to distribute this program under the terms of
20  * the Unmodified Binary Distribution Licence (as given in the file
21  * COPYING.UBDL), provided that you have satisfied its requirements.
22  */
23 
24 FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL );
25 
26 #include <stddef.h>
27 #include <string.h>
28 #include <stdlib.h>
29 #include <stdio.h>
30 #include <errno.h>
31 #include <assert.h>
32 #include <libgen.h>
33 #include <syslog.h>
34 #include <ipxe/list.h>
35 #include <ipxe/umalloc.h>
36 #include <ipxe/uri.h>
37 #include <ipxe/image.h>
38 
39 /** @file
40  *
41  * Executable images
42  *
43  */
44 
45 /* Disambiguate the various error causes */
46 #define EACCES_UNTRUSTED \
47  __einfo_error ( EINFO_EACCES_UNTRUSTED )
48 #define EINFO_EACCES_UNTRUSTED \
49  __einfo_uniqify ( EINFO_EACCES, 0x01, "Untrusted image" )
50 #define EACCES_PERMANENT \
51  __einfo_error ( EINFO_EACCES_PERMANENT )
52 #define EINFO_EACCES_PERMANENT \
53  __einfo_uniqify ( EINFO_EACCES, 0x02, "Trust requirement is permanent" )
54 
55 /** List of registered images */
57 
58 /** Currently-executing image */
60 
61 /** Current image trust requirement */
62 static int require_trusted_images = 0;
63 
64 /** Prevent changes to image trust requirement */
66 
67 /**
68  * Free executable image
69  *
70  * @v refcnt Reference counter
71  */
72 static void free_image ( struct refcnt *refcnt ) {
73  struct image *image = container_of ( refcnt, struct image, refcnt );
74 
75  DBGC ( image, "IMAGE %s freed\n", image->name );
76  free ( image->name );
77  free ( image->cmdline );
78  uri_put ( image->uri );
79  ufree ( image->data );
81  free ( image );
82 }
83 
84 /**
85  * Allocate executable image
86  *
87  * @v uri URI, or NULL
88  * @ret image Executable image
89  */
90 struct image * alloc_image ( struct uri *uri ) {
91  struct image *image;
92  int rc;
93 
94  /* Allocate image */
95  image = zalloc ( sizeof ( *image ) );
96  if ( ! image )
97  goto err_alloc;
98 
99  /* Initialise image */
101  if ( uri && ( ( rc = image_set_uri ( image, uri ) ) != 0 ) )
102  goto err_set_uri;
103 
104  return image;
105 
106  err_set_uri:
107  image_put ( image );
108  err_alloc:
109  return NULL;
110 }
111 
112 /**
113  * Set image URI
114  *
115  * @v image Image
116  * @v uri New image URI
117  * @ret rc Return status code
118  */
119 int image_set_uri ( struct image *image, struct uri *uri ) {
120  const char *name;
121  int rc;
122 
123  /* Set name, if image does not already have one */
124  if ( uri->path && ( ! ( image->name && image->name[0] ) ) ) {
125  name = basename ( ( char * ) uri->path );
126  if ( ( rc = image_set_name ( image, name ) ) != 0 )
127  return rc;
128  }
129 
130  /* Update image URI */
131  uri_put ( image->uri );
132  image->uri = uri_get ( uri );
133 
134  return 0;
135 }
136 
137 /**
138  * Set image name
139  *
140  * @v image Image
141  * @v name New image name
142  * @ret rc Return status code
143  */
144 int image_set_name ( struct image *image, const char *name ) {
145  char *name_copy;
146 
147  /* Duplicate name */
148  name_copy = strdup ( name );
149  if ( ! name_copy )
150  return -ENOMEM;
151 
152  /* Replace existing name */
153  free ( image->name );
154  image->name = name_copy;
155 
156  return 0;
157 }
158 
159 /**
160  * Set image command line
161  *
162  * @v image Image
163  * @v cmdline New image command line, or NULL
164  * @ret rc Return status code
165  */
166 int image_set_cmdline ( struct image *image, const char *cmdline ) {
167 
168  free ( image->cmdline );
169  image->cmdline = NULL;
170  if ( cmdline ) {
171  image->cmdline = strdup ( cmdline );
172  if ( ! image->cmdline )
173  return -ENOMEM;
174  }
175  return 0;
176 }
177 
178 /**
179  * Determine image type
180  *
181  * @v image Executable image
182  * @ret rc Return status code
183  */
184 static int image_probe ( struct image *image ) {
185  struct image_type *type;
186  int rc;
187 
188  /* Try each type in turn */
190  if ( ( rc = type->probe ( image ) ) == 0 ) {
191  image->type = type;
192  DBGC ( image, "IMAGE %s is %s\n",
193  image->name, type->name );
194  return 0;
195  }
196  DBGC ( image, "IMAGE %s is not %s: %s\n", image->name,
197  type->name, strerror ( rc ) );
198  }
199 
200  DBGC ( image, "IMAGE %s format not recognised\n", image->name );
201  return -ENOTSUP;
202 }
203 
204 /**
205  * Register executable image
206  *
207  * @v image Executable image
208  * @ret rc Return status code
209  */
210 int register_image ( struct image *image ) {
211  static unsigned int imgindex = 0;
212  char name[8]; /* "imgXXXX" */
213  int rc;
214 
215  /* Create image name if it doesn't already have one */
216  if ( ! image->name ) {
217  snprintf ( name, sizeof ( name ), "img%d", imgindex++ );
218  if ( ( rc = image_set_name ( image, name ) ) != 0 )
219  return rc;
220  }
221 
222  /* Avoid ending up with multiple "selected" images on
223  * re-registration
224  */
225  if ( image_find_selected() )
227 
228  /* Add to image list */
229  image_get ( image );
231  list_add_tail ( &image->list, &images );
232  DBGC ( image, "IMAGE %s at [%lx,%lx) registered\n",
233  image->name, user_to_phys ( image->data, 0 ),
234  user_to_phys ( image->data, image->len ) );
235 
236  /* Try to detect image type, if applicable. Ignore failures,
237  * since we expect to handle some unrecognised images
238  * (e.g. kernel initrds, multiboot modules, random files
239  * provided via our EFI virtual filesystem, etc).
240  */
241  if ( ! image->type )
242  image_probe ( image );
243 
244  return 0;
245 }
246 
247 /**
248  * Unregister executable image
249  *
250  * @v image Executable image
251  */
252 void unregister_image ( struct image *image ) {
253 
254  /* Do nothing unless image is registered */
255  if ( ! ( image->flags & IMAGE_REGISTERED ) )
256  return;
257 
258  DBGC ( image, "IMAGE %s unregistered\n", image->name );
259  list_del ( &image->list );
261  image_put ( image );
262 }
263 
264 /**
265  * Find image by name
266  *
267  * @v name Image name
268  * @ret image Executable image, or NULL
269  */
270 struct image * find_image ( const char *name ) {
271  struct image *image;
272 
274  if ( strcmp ( image->name, name ) == 0 )
275  return image;
276  }
277 
278  return NULL;
279 }
280 
281 /**
282  * Execute image
283  *
284  * @v image Executable image
285  * @ret rc Return status code
286  *
287  * The image must already be registered. Note that executing an image
288  * may cause it to unregister itself. The caller must therefore
289  * assume that the image pointer becomes invalid.
290  */
291 int image_exec ( struct image *image ) {
292  struct image *saved_current_image;
293  struct image *replacement = NULL;
294  struct uri *old_cwuri;
295  int rc;
296 
297  /* Sanity check */
299 
300  /* Switch current working directory to be that of the image itself */
301  old_cwuri = uri_get ( cwuri );
302  churi ( image->uri );
303 
304  /* Preserve record of any currently-running image */
305  saved_current_image = current_image;
306 
307  /* Take out a temporary reference to the image. This allows
308  * the image to unregister itself if necessary, without
309  * automatically freeing itself.
310  */
312 
313  /* Check that this image can be executed */
314  if ( ! ( image->type && image->type->exec ) ) {
315  rc = -ENOEXEC;
316  goto err;
317  }
318 
319  /* Check that image is trusted (if applicable) */
320  if ( require_trusted_images && ! ( image->flags & IMAGE_TRUSTED ) ) {
321  DBGC ( image, "IMAGE %s is not trusted\n", image->name );
322  rc = -EACCES_UNTRUSTED;
323  goto err;
324  }
325 
326  /* Record boot attempt */
327  syslog ( LOG_NOTICE, "Executing \"%s\"\n", image->name );
328 
329  /* Try executing the image */
330  if ( ( rc = image->type->exec ( image ) ) != 0 ) {
331  DBGC ( image, "IMAGE %s could not execute: %s\n",
332  image->name, strerror ( rc ) );
333  /* Do not return yet; we still have clean-up to do */
334  }
335 
336  /* Record result of boot attempt */
337  if ( rc == 0 ) {
338  syslog ( LOG_NOTICE, "Execution of \"%s\" completed\n",
339  image->name );
340  } else {
341  syslog ( LOG_ERR, "Execution of \"%s\" failed: %s\n",
342  image->name, strerror ( rc ) );
343  }
344 
345  /* Pick up replacement image before we drop the original
346  * image's temporary reference. The replacement image must
347  * already be registered, so we don't need to hold a temporary
348  * reference (which would complicate the tail-recursion).
349  */
350  replacement = image->replacement;
351  if ( replacement )
352  assert ( replacement->flags & IMAGE_REGISTERED );
353 
354  err:
355  /* Unregister image if applicable */
358 
359  /* Debug message for tail-recursion. Placed here because the
360  * image_put() may end up freeing the image.
361  */
362  if ( replacement ) {
363  DBGC ( image, "IMAGE %s replacing self with IMAGE %s\n",
364  image->name, replacement->name );
365  }
366 
367  /* Drop temporary reference to the original image */
368  image_put ( image );
369 
370  /* Restore previous currently-running image */
371  current_image = saved_current_image;
372 
373  /* Reset current working directory */
374  churi ( old_cwuri );
375  uri_put ( old_cwuri );
376 
377  /* Tail-recurse into replacement image, if one exists */
378  if ( replacement )
379  return image_exec ( replacement );
380 
381  return rc;
382 }
383 
384 /**
385  * Set replacement image
386  *
387  * @v replacement Replacement image
388  * @ret rc Return status code
389  *
390  * The replacement image must already be registered, and must remain
391  * registered until the currently-executing image returns.
392  */
393 int image_replace ( struct image *replacement ) {
394  struct image *image = current_image;
395  int rc;
396 
397  /* Sanity check */
399 
400  /* Fail unless there is a currently-executing image */
401  if ( ! image ) {
402  rc = -ENOTTY;
403  DBGC ( replacement, "IMAGE %s cannot replace non-existent "
404  "image: %s\n", replacement->name, strerror ( rc ) );
405  return rc;
406  }
407 
408  /* Check that the replacement image can be executed */
409  if ( ! ( replacement->type && replacement->type->exec ) )
410  return -ENOEXEC;
411 
412  /* Clear any existing replacement */
414 
415  /* Set replacement */
417  DBGC ( image, "IMAGE %s will replace self with IMAGE %s\n",
418  image->name, replacement->name );
419 
420  return 0;
421 }
422 
423 /**
424  * Select image for execution
425  *
426  * @v image Executable image
427  * @ret rc Return status code
428  */
429 int image_select ( struct image *image ) {
430  struct image *tmp;
431 
432  /* Unselect all other images */
433  for_each_image ( tmp )
434  tmp->flags &= ~IMAGE_SELECTED;
435 
436  /* Check that this image can be executed */
437  if ( ! ( image->type && image->type->exec ) )
438  return -ENOEXEC;
439 
440  /* Mark image as selected */
442 
443  return 0;
444 }
445 
446 /**
447  * Find selected image
448  *
449  * @ret image Executable image, or NULL
450  */
451 struct image * image_find_selected ( void ) {
452  struct image *image;
453 
454  for_each_image ( image ) {
455  if ( image->flags & IMAGE_SELECTED )
456  return image;
457  }
458  return NULL;
459 }
460 
461 /**
462  * Change image trust requirement
463  *
464  * @v require_trusted Require trusted images
465  * @v permanent Make trust requirement permanent
466  * @ret rc Return status code
467  */
468 int image_set_trust ( int require_trusted, int permanent ) {
469 
470  /* Update trust requirement, if permitted to do so */
472  require_trusted_images = require_trusted;
474  }
475 
476  /* Fail if we attempted to change the trust requirement but
477  * were not permitted to do so.
478  */
479  if ( require_trusted_images != require_trusted )
480  return -EACCES_PERMANENT;
481 
482  return 0;
483 }
#define IMAGE_TYPES
Executable image type table.
Definition: image.h:140
int image_set_trust(int require_trusted, int permanent)
Change image trust requirement.
Definition: image.c:468
unsigned int flags
Flags.
Definition: image.h:36
static int require_trusted_images_permanent
Prevent changes to image trust requirement.
Definition: image.c:65
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
const char * name
Definition: ath9k_hw.c:1984
struct image * current_image
Currently-executing image.
Definition: image.c:59
int image_select(struct image *image)
Select image for execution.
Definition: image.c:429
int image_set_uri(struct image *image, struct uri *uri)
Set image URI.
Definition: image.c:119
userptr_t data
Raw file image.
Definition: image.h:41
static void uri_put(struct uri *uri)
Decrement URI reference count.
Definition: uri.h:188
static struct uri * uri_get(struct uri *uri)
Increment URI reference count.
Definition: uri.h:177
struct image * find_image(const char *name)
Find image by name.
Definition: image.c:270
#define ref_init(refcnt, free)
Initialise a reference counter.
Definition: refcnt.h:64
Error codes.
#define EACCES_UNTRUSTED
Definition: image.c:46
#define ENOEXEC
Exec format error.
Definition: errno.h:519
struct image_type * type
Image type, if known.
Definition: image.h:46
uint8_t type
Type.
Definition: ena.h:16
static struct image * image_get(struct image *image)
Increment reference count on an image.
Definition: image.h:196
unsigned long user_to_phys(userptr_t userptr, off_t offset)
Convert user pointer to physical address.
#define DBGC(...)
Definition: compiler.h:505
An executable image type.
Definition: image.h:76
#define EACCES_PERMANENT
Definition: image.c:50
An executable image.
Definition: image.h:24
#define LOG_ERR
Error: error conditions.
Definition: syslog.h:35
Uniform Resource Identifiers.
#define IMAGE_AUTO_UNREGISTER
Image will be automatically unregistered after execution.
Definition: image.h:73
int(* exec)(struct image *image)
Execute image.
Definition: image.h:94
#define ENOTSUP
Operation not supported.
Definition: errno.h:589
char * cmdline
Command line to pass to image.
Definition: image.h:39
A doubly-linked list entry (or list head)
Definition: list.h:18
A reference counter.
Definition: refcnt.h:26
int image_exec(struct image *image)
Execute image.
Definition: image.c:291
static void free_image(struct refcnt *refcnt)
Free executable image.
Definition: image.c:72
#define list_del(list)
Delete an entry from a list.
Definition: list.h:119
static int image_probe(struct image *image)
Determine image type.
Definition: image.c:184
#define ENOMEM
Not enough space.
Definition: errno.h:534
FILE_LICENCE(GPL2_OR_LATER_OR_UBDL)
Assertions.
void churi(struct uri *uri)
Change working URI.
Definition: cwuri.c:45
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
#define IMAGE_SELECTED
Image is selected for execution.
Definition: image.h:67
#define container_of(ptr, type, field)
Get containing structure.
Definition: stddef.h:35
Executable images.
#define list_for_each_entry(pos, head, member)
Iterate over entries in a list.
Definition: list.h:420
#define list_add_tail(new, head)
Add a new entry to the tail of a list.
Definition: list.h:93
const char * path
Path.
Definition: uri.h:66
#define IMAGE_REGISTERED
Image is registered.
Definition: image.h:64
Linked lists.
int register_image(struct image *image)
Register executable image.
Definition: image.c:210
#define for_each_image(image)
Iterate over all registered images.
Definition: image.h:149
System logger.
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
char * basename(char *path)
Return base name from path.
Definition: basename.c:42
static void(* free)(struct refcnt *refcnt))
Definition: refcnt.h:54
void * zalloc(size_t size)
Allocate cleared memory.
Definition: malloc.c:624
size_t len
Length of raw file image.
Definition: image.h:43
int image_replace(struct image *replacement)
Set replacement image.
Definition: image.c:393
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
#define IMAGE_TRUSTED
Image is trusted.
Definition: image.h:70
uint8_t * tmp
Definition: entropy.h:156
char * strdup(const char *src)
Duplicate string.
Definition: string.c:350
User memory allocation.
#define for_each_table_entry(pointer, table)
Iterate through all entries within a linker table.
Definition: tables.h:358
struct uri * uri
URI of image.
Definition: image.h:32
static void image_put(struct image *image)
Decrement reference count on an image.
Definition: image.h:206
struct image * image_find_selected(void)
Find selected image.
Definition: image.c:451
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:252
static __always_inline void ufree(userptr_t userptr)
Free external memory.
Definition: umalloc.h:65
#define ENOTTY
Inappropriate I/O control operation.
Definition: errno.h:594
int strcmp(const char *first, const char *second)
Compare strings.
Definition: string.c:157
#define syslog(priority, fmt,...)
Write message to system log.
Definition: syslog.h:93
struct image * replacement
Replacement image.
Definition: image.h:60
int image_set_cmdline(struct image *image, const char *cmdline)
Set image command line.
Definition: image.c:166
int snprintf(char *buf, size_t size, const char *fmt,...)
Write a formatted string to a buffer.
Definition: vsprintf.c:382
A Uniform Resource Identifier.
Definition: uri.h:50
static int require_trusted_images
Current image trust requirement.
Definition: image.c:62
#define LIST_HEAD_INIT(list)
Initialise a static list head.
Definition: list.h:30
struct list_head list
List of registered images.
Definition: image.h:29
struct uri * cwuri
Current working URI.
Definition: cwuri.c:38
uint32_t cmdline
Definition: multiboot.h:16
struct image * alloc_image(struct uri *uri)
Allocate executable image.
Definition: image.c:90
char * name
Name.
Definition: image.h:34
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
String functions.
#define LOG_NOTICE
Notice: normal but significant conditions.
Definition: syslog.h:41
struct refcnt refcnt
Reference count.
Definition: image.h:26