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  * Set image length
180  *
181  * @v image Image
182  * @v len Length of image data
183  * @ret rc Return status code
184  */
185 int image_set_len ( struct image *image, size_t len ) {
186  userptr_t new;
187 
188  /* (Re)allocate image data */
189  new = urealloc ( image->data, len );
190  if ( ! new )
191  return -ENOMEM;
192  image->data = new;
193  image->len = len;
194 
195  return 0;
196 }
197 
198 /**
199  * Set image data
200  *
201  * @v image Image
202  * @v data Image data
203  * @v len Length of image data
204  * @ret rc Return status code
205  */
206 int image_set_data ( struct image *image, userptr_t data, size_t len ) {
207  int rc;
208 
209  /* Set image length */
210  if ( ( rc = image_set_len ( image, len ) ) != 0 )
211  return rc;
212 
213  /* Copy in new image data */
214  memcpy_user ( image->data, 0, data, 0, len );
215 
216  return 0;
217 }
218 
219 /**
220  * Determine image type
221  *
222  * @v image Executable image
223  * @ret rc Return status code
224  */
225 static int image_probe ( struct image *image ) {
226  struct image_type *type;
227  int rc;
228 
229  /* Try each type in turn */
231  if ( ( rc = type->probe ( image ) ) == 0 ) {
232  image->type = type;
233  DBGC ( image, "IMAGE %s is %s\n",
234  image->name, type->name );
235  return 0;
236  }
237  DBGC ( image, "IMAGE %s is not %s: %s\n", image->name,
238  type->name, strerror ( rc ) );
239  }
240 
241  DBGC ( image, "IMAGE %s format not recognised\n", image->name );
242  return -ENOTSUP;
243 }
244 
245 /**
246  * Register executable image
247  *
248  * @v image Executable image
249  * @ret rc Return status code
250  */
251 int register_image ( struct image *image ) {
252  static unsigned int imgindex = 0;
253  char name[8]; /* "imgXXXX" */
254  int rc;
255 
256  /* Create image name if it doesn't already have one */
257  if ( ! image->name ) {
258  snprintf ( name, sizeof ( name ), "img%d", imgindex++ );
259  if ( ( rc = image_set_name ( image, name ) ) != 0 )
260  return rc;
261  }
262 
263  /* Avoid ending up with multiple "selected" images on
264  * re-registration
265  */
266  if ( image_find_selected() )
268 
269  /* Add to image list */
270  image_get ( image );
272  list_add_tail ( &image->list, &images );
273  DBGC ( image, "IMAGE %s at [%lx,%lx) registered\n",
274  image->name, user_to_phys ( image->data, 0 ),
275  user_to_phys ( image->data, image->len ) );
276 
277  /* Try to detect image type, if applicable. Ignore failures,
278  * since we expect to handle some unrecognised images
279  * (e.g. kernel initrds, multiboot modules, random files
280  * provided via our EFI virtual filesystem, etc).
281  */
282  if ( ! image->type )
283  image_probe ( image );
284 
285  return 0;
286 }
287 
288 /**
289  * Unregister executable image
290  *
291  * @v image Executable image
292  */
293 void unregister_image ( struct image *image ) {
294 
295  /* Do nothing unless image is registered */
296  if ( ! ( image->flags & IMAGE_REGISTERED ) )
297  return;
298 
299  DBGC ( image, "IMAGE %s unregistered\n", image->name );
300  list_del ( &image->list );
302  image_put ( image );
303 }
304 
305 /**
306  * Find image by name
307  *
308  * @v name Image name
309  * @ret image Executable image, or NULL
310  */
311 struct image * find_image ( const char *name ) {
312  struct image *image;
313 
315  if ( strcmp ( image->name, name ) == 0 )
316  return image;
317  }
318 
319  return NULL;
320 }
321 
322 /**
323  * Execute image
324  *
325  * @v image Executable image
326  * @ret rc Return status code
327  *
328  * The image must already be registered. Note that executing an image
329  * may cause it to unregister itself. The caller must therefore
330  * assume that the image pointer becomes invalid.
331  */
332 int image_exec ( struct image *image ) {
333  struct image *saved_current_image;
334  struct image *replacement = NULL;
335  struct uri *old_cwuri;
336  int rc;
337 
338  /* Sanity check */
340 
341  /* Switch current working directory to be that of the image
342  * itself, if applicable
343  */
344  old_cwuri = uri_get ( cwuri );
345  if ( image->uri )
346  churi ( image->uri );
347 
348  /* Preserve record of any currently-running image */
349  saved_current_image = current_image;
350 
351  /* Take out a temporary reference to the image. This allows
352  * the image to unregister itself if necessary, without
353  * automatically freeing itself.
354  */
356 
357  /* Check that this image can be executed */
358  if ( ! ( image->type && image->type->exec ) ) {
359  rc = -ENOEXEC;
360  goto err;
361  }
362 
363  /* Check that image is trusted (if applicable) */
364  if ( require_trusted_images && ! ( image->flags & IMAGE_TRUSTED ) ) {
365  DBGC ( image, "IMAGE %s is not trusted\n", image->name );
366  rc = -EACCES_UNTRUSTED;
367  goto err;
368  }
369 
370  /* Record boot attempt */
371  syslog ( LOG_NOTICE, "Executing \"%s\"\n", image->name );
372 
373  /* Try executing the image */
374  if ( ( rc = image->type->exec ( image ) ) != 0 ) {
375  DBGC ( image, "IMAGE %s could not execute: %s\n",
376  image->name, strerror ( rc ) );
377  /* Do not return yet; we still have clean-up to do */
378  }
379 
380  /* Record result of boot attempt */
381  if ( rc == 0 ) {
382  syslog ( LOG_NOTICE, "Execution of \"%s\" completed\n",
383  image->name );
384  } else {
385  syslog ( LOG_ERR, "Execution of \"%s\" failed: %s\n",
386  image->name, strerror ( rc ) );
387  }
388 
389  /* Pick up replacement image before we drop the original
390  * image's temporary reference. The replacement image must
391  * already be registered, so we don't need to hold a temporary
392  * reference (which would complicate the tail-recursion).
393  */
394  replacement = image->replacement;
395  if ( replacement )
396  assert ( replacement->flags & IMAGE_REGISTERED );
397 
398  err:
399  /* Unregister image if applicable */
402 
403  /* Debug message for tail-recursion. Placed here because the
404  * image_put() may end up freeing the image.
405  */
406  if ( replacement ) {
407  DBGC ( image, "IMAGE %s replacing self with IMAGE %s\n",
408  image->name, replacement->name );
409  }
410 
411  /* Drop temporary reference to the original image */
412  image_put ( image );
413 
414  /* Restore previous currently-running image */
415  current_image = saved_current_image;
416 
417  /* Reset current working directory */
418  churi ( old_cwuri );
419  uri_put ( old_cwuri );
420 
421  /* Tail-recurse into replacement image, if one exists */
422  if ( replacement )
423  return image_exec ( replacement );
424 
425  return rc;
426 }
427 
428 /**
429  * Set replacement image
430  *
431  * @v replacement Replacement image
432  * @ret rc Return status code
433  *
434  * The replacement image must already be registered, and must remain
435  * registered until the currently-executing image returns.
436  */
437 int image_replace ( struct image *replacement ) {
438  struct image *image = current_image;
439  int rc;
440 
441  /* Sanity check */
443 
444  /* Fail unless there is a currently-executing image */
445  if ( ! image ) {
446  rc = -ENOTTY;
447  DBGC ( replacement, "IMAGE %s cannot replace non-existent "
448  "image: %s\n", replacement->name, strerror ( rc ) );
449  return rc;
450  }
451 
452  /* Check that the replacement image can be executed */
453  if ( ! ( replacement->type && replacement->type->exec ) )
454  return -ENOEXEC;
455 
456  /* Clear any existing replacement */
458 
459  /* Set replacement */
461  DBGC ( image, "IMAGE %s will replace self with IMAGE %s\n",
462  image->name, replacement->name );
463 
464  return 0;
465 }
466 
467 /**
468  * Select image for execution
469  *
470  * @v image Executable image
471  * @ret rc Return status code
472  */
473 int image_select ( struct image *image ) {
474  struct image *tmp;
475 
476  /* Unselect all other images */
477  for_each_image ( tmp )
478  tmp->flags &= ~IMAGE_SELECTED;
479 
480  /* Check that this image can be executed */
481  if ( ! ( image->type && image->type->exec ) )
482  return -ENOEXEC;
483 
484  /* Mark image as selected */
486 
487  return 0;
488 }
489 
490 /**
491  * Find selected image
492  *
493  * @ret image Executable image, or NULL
494  */
495 struct image * image_find_selected ( void ) {
496  struct image *image;
497 
498  for_each_image ( image ) {
499  if ( image->flags & IMAGE_SELECTED )
500  return image;
501  }
502  return NULL;
503 }
504 
505 /**
506  * Change image trust requirement
507  *
508  * @v require_trusted Require trusted images
509  * @v permanent Make trust requirement permanent
510  * @ret rc Return status code
511  */
512 int image_set_trust ( int require_trusted, int permanent ) {
513 
514  /* Update trust requirement, if permitted to do so */
516  require_trusted_images = require_trusted;
518  }
519 
520  /* Fail if we attempted to change the trust requirement but
521  * were not permitted to do so.
522  */
523  if ( require_trusted_images != require_trusted )
524  return -EACCES_PERMANENT;
525 
526  return 0;
527 }
528 
529 /**
530  * Create registered image from block of memory
531  *
532  * @v name Name
533  * @v data Image data
534  * @v len Length
535  * @ret image Image, or NULL on error
536  */
537 struct image * image_memory ( const char *name, userptr_t data, size_t len ) {
538  struct image *image;
539  int rc;
540 
541  /* Allocate image */
542  image = alloc_image ( NULL );
543  if ( ! image ) {
544  rc = -ENOMEM;
545  goto err_alloc_image;
546  }
547 
548  /* Set name */
549  if ( ( rc = image_set_name ( image, name ) ) != 0 )
550  goto err_set_name;
551 
552  /* Set data */
553  if ( ( rc = image_set_data ( image, data, len ) ) != 0 )
554  goto err_set_data;
555 
556  /* Register image */
557  if ( ( rc = register_image ( image ) ) != 0 )
558  goto err_register;
559 
560  /* Drop local reference to image */
561  image_put ( image );
562 
563  return image;
564 
565  err_register:
566  err_set_data:
567  err_set_name:
568  image_put ( image );
569  err_alloc_image:
570  return NULL;
571 }
#define IMAGE_TYPES
Executable image type table.
Definition: image.h:148
int image_set_trust(int require_trusted, int permanent)
Change image trust requirement.
Definition: image.c:512
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:473
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:205
static struct uri * uri_get(struct uri *uri)
Increment URI reference count.
Definition: uri.h:194
struct image * find_image(const char *name)
Find image by name.
Definition: image.c:311
#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
uint32_t type
Operating system type.
Definition: ena.h:12
static struct image * image_get(struct image *image)
Increment reference count on an image.
Definition: image.h:211
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
struct image * image_memory(const char *name, userptr_t data, size_t len)
Create registered image from block of memory.
Definition: image.c:537
#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:332
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:225
#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 (after URI decoding)
Definition: uri.h:80
#define IMAGE_REGISTERED
Image is registered.
Definition: image.h:64
userptr_t urealloc(userptr_t userptr, size_t new_size)
Reallocate external memory.
Linked lists.
int register_image(struct image *image)
Register executable image.
Definition: image.c:251
#define for_each_image(image)
Iterate over all registered images.
Definition: image.h:157
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:437
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:380
User memory allocation.
#define for_each_table_entry(pointer, table)
Iterate through all entries within a linker table.
Definition: tables.h:385
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:221
int image_set_data(struct image *image, userptr_t data, size_t len)
Set image data.
Definition: image.c:206
struct image * image_find_selected(void)
Find selected image.
Definition: image.c:495
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:293
int image_set_len(struct image *image, size_t len)
Set image length.
Definition: image.c:185
static __always_inline void ufree(userptr_t userptr)
Free external memory.
Definition: umalloc.h:65
uint32_t len
Length.
Definition: ena.h:14
#define ENOTTY
Inappropriate I/O control operation.
Definition: errno.h:594
int strcmp(const char *first, const char *second)
Compare strings.
Definition: string.c:173
#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:64
struct arbelprm_port_state_change_st data
Message.
Definition: arbel.h:12
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
void memcpy_user(userptr_t dest, off_t dest_off, userptr_t src, off_t src_off, size_t len)
Copy data between user buffers.
unsigned long userptr_t
A pointer to a user buffer.
Definition: uaccess.h:33
struct refcnt refcnt
Reference count.
Definition: image.h:26