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 <ctype.h>
31 #include <errno.h>
32 #include <assert.h>
33 #include <libgen.h>
34 #include <syslog.h>
35 #include <ipxe/list.h>
36 #include <ipxe/umalloc.h>
37 #include <ipxe/uri.h>
38 #include <ipxe/image.h>
39 
40 /** @file
41  *
42  * Executable images
43  *
44  */
45 
46 /* Disambiguate the various error causes */
47 #define EACCES_UNTRUSTED \
48  __einfo_error ( EINFO_EACCES_UNTRUSTED )
49 #define EINFO_EACCES_UNTRUSTED \
50  __einfo_uniqify ( EINFO_EACCES, 0x01, "Untrusted image" )
51 #define EACCES_PERMANENT \
52  __einfo_error ( EINFO_EACCES_PERMANENT )
53 #define EINFO_EACCES_PERMANENT \
54  __einfo_uniqify ( EINFO_EACCES, 0x02, "Trust requirement is permanent" )
55 
56 /** List of registered images */
58 
59 /** Currently-executing image */
61 
62 /** Current image trust requirement */
63 static int require_trusted_images = 0;
64 
65 /** Prevent changes to image trust requirement */
67 
68 /**
69  * Free executable image
70  *
71  * @v refcnt Reference counter
72  */
73 static void free_image ( struct refcnt *refcnt ) {
74  struct image *image = container_of ( refcnt, struct image, refcnt );
75 
76  DBGC ( image, "IMAGE %s freed\n", image->name );
77  free ( image->name );
78  free ( image->cmdline );
79  uri_put ( image->uri );
80  ufree ( image->data );
82  free ( image );
83 }
84 
85 /**
86  * Allocate executable image
87  *
88  * @v uri URI, or NULL
89  * @ret image Executable image
90  */
91 struct image * alloc_image ( struct uri *uri ) {
92  struct image *image;
93  int rc;
94 
95  /* Allocate image */
96  image = zalloc ( sizeof ( *image ) );
97  if ( ! image )
98  goto err_alloc;
99 
100  /* Initialise image */
102  if ( uri && ( ( rc = image_set_uri ( image, uri ) ) != 0 ) )
103  goto err_set_uri;
104 
105  return image;
106 
107  err_set_uri:
108  image_put ( image );
109  err_alloc:
110  return NULL;
111 }
112 
113 /**
114  * Set image URI
115  *
116  * @v image Image
117  * @v uri New image URI
118  * @ret rc Return status code
119  */
120 int image_set_uri ( struct image *image, struct uri *uri ) {
121  const char *name;
122  int rc;
123 
124  /* Set name, if image does not already have one */
125  if ( uri->path && ( ! ( image->name && image->name[0] ) ) ) {
126  name = basename ( ( char * ) uri->path );
127  if ( ( rc = image_set_name ( image, name ) ) != 0 )
128  return rc;
129  }
130 
131  /* Update image URI */
132  uri_put ( image->uri );
133  image->uri = uri_get ( uri );
134 
135  return 0;
136 }
137 
138 /**
139  * Set image name
140  *
141  * @v image Image
142  * @v name New image name
143  * @ret rc Return status code
144  */
145 int image_set_name ( struct image *image, const char *name ) {
146  char *name_copy;
147 
148  /* Duplicate name */
149  name_copy = strdup ( name );
150  if ( ! name_copy )
151  return -ENOMEM;
152 
153  /* Replace existing name */
154  free ( image->name );
155  image->name = name_copy;
156 
157  return 0;
158 }
159 
160 /**
161  * Set image command line
162  *
163  * @v image Image
164  * @v cmdline New image command line, or NULL
165  * @ret rc Return status code
166  */
167 int image_set_cmdline ( struct image *image, const char *cmdline ) {
168 
169  free ( image->cmdline );
170  image->cmdline = NULL;
171  if ( cmdline ) {
172  image->cmdline = strdup ( cmdline );
173  if ( ! image->cmdline )
174  return -ENOMEM;
175  }
176  return 0;
177 }
178 
179 /**
180  * Set image length
181  *
182  * @v image Image
183  * @v len Length of image data
184  * @ret rc Return status code
185  */
186 int image_set_len ( struct image *image, size_t len ) {
187  userptr_t new;
188 
189  /* (Re)allocate image data */
190  new = urealloc ( image->data, len );
191  if ( ! new )
192  return -ENOMEM;
193  image->data = new;
194  image->len = len;
195 
196  return 0;
197 }
198 
199 /**
200  * Set image data
201  *
202  * @v image Image
203  * @v data Image data
204  * @v len Length of image data
205  * @ret rc Return status code
206  */
207 int image_set_data ( struct image *image, userptr_t data, size_t len ) {
208  int rc;
209 
210  /* Set image length */
211  if ( ( rc = image_set_len ( image, len ) ) != 0 )
212  return rc;
213 
214  /* Copy in new image data */
215  memcpy_user ( image->data, 0, data, 0, len );
216 
217  return 0;
218 }
219 
220 /**
221  * Determine image type
222  *
223  * @v image Executable image
224  * @ret rc Return status code
225  */
226 static int image_probe ( struct image *image ) {
227  struct image_type *type;
228  int rc;
229 
230  /* Try each type in turn */
232  if ( ( rc = type->probe ( image ) ) == 0 ) {
233  image->type = type;
234  DBGC ( image, "IMAGE %s is %s\n",
235  image->name, type->name );
236  return 0;
237  }
238  DBGC ( image, "IMAGE %s is not %s: %s\n", image->name,
239  type->name, strerror ( rc ) );
240  }
241 
242  DBGC ( image, "IMAGE %s format not recognised\n", image->name );
243  return -ENOTSUP;
244 }
245 
246 /**
247  * Register executable image
248  *
249  * @v image Executable image
250  * @ret rc Return status code
251  */
252 int register_image ( struct image *image ) {
253  static unsigned int imgindex = 0;
254  char name[8]; /* "imgXXXX" */
255  int rc;
256 
257  /* Create image name if it doesn't already have one */
258  if ( ! image->name ) {
259  snprintf ( name, sizeof ( name ), "img%d", imgindex++ );
260  if ( ( rc = image_set_name ( image, name ) ) != 0 )
261  return rc;
262  }
263 
264  /* Avoid ending up with multiple "selected" images on
265  * re-registration
266  */
267  if ( image_find_selected() )
269 
270  /* Add to image list */
271  image_get ( image );
273  list_add_tail ( &image->list, &images );
274  DBGC ( image, "IMAGE %s at [%lx,%lx) registered\n",
275  image->name, user_to_phys ( image->data, 0 ),
276  user_to_phys ( image->data, image->len ) );
277 
278  /* Try to detect image type, if applicable. Ignore failures,
279  * since we expect to handle some unrecognised images
280  * (e.g. kernel initrds, multiboot modules, random files
281  * provided via our EFI virtual filesystem, etc).
282  */
283  if ( ! image->type )
284  image_probe ( image );
285 
286  return 0;
287 }
288 
289 /**
290  * Unregister executable image
291  *
292  * @v image Executable image
293  */
294 void unregister_image ( struct image *image ) {
295 
296  /* Do nothing unless image is registered */
297  if ( ! ( image->flags & IMAGE_REGISTERED ) )
298  return;
299 
300  DBGC ( image, "IMAGE %s unregistered\n", image->name );
301  list_del ( &image->list );
303  image_put ( image );
304 }
305 
306 /**
307  * Find image by name
308  *
309  * @v name Image name
310  * @ret image Executable image, or NULL
311  */
312 struct image * find_image ( const char *name ) {
313  struct image *image;
314 
315  for_each_image ( image ) {
316  if ( strcmp ( image->name, name ) == 0 )
317  return image;
318  }
319 
320  return NULL;
321 }
322 
323 /**
324  * Execute image
325  *
326  * @v image Executable image
327  * @ret rc Return status code
328  *
329  * The image must already be registered. Note that executing an image
330  * may cause it to unregister itself. The caller must therefore
331  * assume that the image pointer becomes invalid.
332  */
333 int image_exec ( struct image *image ) {
334  struct image *saved_current_image;
335  struct image *replacement = NULL;
336  struct uri *old_cwuri;
337  int rc;
338 
339  /* Sanity check */
341 
342  /* Switch current working directory to be that of the image
343  * itself, if applicable
344  */
345  old_cwuri = uri_get ( cwuri );
346  if ( image->uri )
347  churi ( image->uri );
348 
349  /* Preserve record of any currently-running image */
350  saved_current_image = current_image;
351 
352  /* Take out a temporary reference to the image, so that it
353  * does not get freed when temporarily unregistered.
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  /* Temporarily unregister the image during its execution */
375 
376  /* Try executing the image */
377  if ( ( rc = image->type->exec ( image ) ) != 0 ) {
378  DBGC ( image, "IMAGE %s could not execute: %s\n",
379  image->name, strerror ( rc ) );
380  /* Do not return yet; we still have clean-up to do */
381  }
382 
383  /* Record result of boot attempt */
384  if ( rc == 0 ) {
385  syslog ( LOG_NOTICE, "Execution of \"%s\" completed\n",
386  image->name );
387  } else {
388  syslog ( LOG_ERR, "Execution of \"%s\" failed: %s\n",
389  image->name, strerror ( rc ) );
390  }
391 
392  /* Re-register image (unless due to be replaced) */
393  if ( ! image->replacement )
394  register_image ( image );
395 
396  /* Pick up replacement image before we drop the original
397  * image's temporary reference. The replacement image must
398  * already be registered, so we don't need to hold a temporary
399  * reference (which would complicate the tail-recursion).
400  */
401  replacement = image->replacement;
402  if ( replacement )
403  assert ( replacement->flags & IMAGE_REGISTERED );
404 
405  err:
406  /* Unregister image if applicable */
409 
410  /* Debug message for tail-recursion. Placed here because the
411  * image_put() may end up freeing the image.
412  */
413  if ( replacement ) {
414  DBGC ( image, "IMAGE %s replacing self with IMAGE %s\n",
415  image->name, replacement->name );
416  }
417 
418  /* Drop temporary reference to the original image */
419  image_put ( image );
420 
421  /* Restore previous currently-running image */
422  current_image = saved_current_image;
423 
424  /* Reset current working directory */
425  churi ( old_cwuri );
426  uri_put ( old_cwuri );
427 
428  /* Tail-recurse into replacement image, if one exists */
429  if ( replacement )
430  return image_exec ( replacement );
431 
432  return rc;
433 }
434 
435 /**
436  * Set replacement image
437  *
438  * @v replacement Replacement image
439  * @ret rc Return status code
440  *
441  * The replacement image must already be registered, and must remain
442  * registered until the currently-executing image returns.
443  */
444 int image_replace ( struct image *replacement ) {
445  struct image *image = current_image;
446  int rc;
447 
448  /* Sanity check */
450 
451  /* Fail unless there is a currently-executing image */
452  if ( ! image ) {
453  rc = -ENOTTY;
454  DBGC ( replacement, "IMAGE %s cannot replace non-existent "
455  "image: %s\n", replacement->name, strerror ( rc ) );
456  return rc;
457  }
458 
459  /* Check that the replacement image can be executed */
460  if ( ! ( replacement->type && replacement->type->exec ) )
461  return -ENOEXEC;
462 
463  /* Clear any existing replacement */
465 
466  /* Set replacement */
468  DBGC ( image, "IMAGE %s will replace self with IMAGE %s\n",
469  image->name, replacement->name );
470 
471  return 0;
472 }
473 
474 /**
475  * Select image for execution
476  *
477  * @v image Executable image
478  * @ret rc Return status code
479  */
480 int image_select ( struct image *image ) {
481  struct image *tmp;
482 
483  /* Unselect all other images */
484  for_each_image ( tmp )
485  tmp->flags &= ~IMAGE_SELECTED;
486 
487  /* Check that this image can be executed */
488  if ( ! ( image->type && image->type->exec ) )
489  return -ENOEXEC;
490 
491  /* Mark image as selected */
493 
494  return 0;
495 }
496 
497 /**
498  * Find selected image
499  *
500  * @ret image Executable image, or NULL
501  */
502 struct image * image_find_selected ( void ) {
503  struct image *image;
504 
505  for_each_image ( image ) {
506  if ( image->flags & IMAGE_SELECTED )
507  return image;
508  }
509  return NULL;
510 }
511 
512 /**
513  * Change image trust requirement
514  *
515  * @v require_trusted Require trusted images
516  * @v permanent Make trust requirement permanent
517  * @ret rc Return status code
518  */
519 int image_set_trust ( int require_trusted, int permanent ) {
520 
521  /* Update trust requirement, if permitted to do so */
523  require_trusted_images = require_trusted;
525  }
526 
527  /* Fail if we attempted to change the trust requirement but
528  * were not permitted to do so.
529  */
530  if ( require_trusted_images != require_trusted )
531  return -EACCES_PERMANENT;
532 
533  return 0;
534 }
535 
536 /**
537  * Create registered image from block of memory
538  *
539  * @v name Name
540  * @v data Image data
541  * @v len Length
542  * @ret image Image, or NULL on error
543  */
544 struct image * image_memory ( const char *name, userptr_t data, size_t len ) {
545  struct image *image;
546  int rc;
547 
548  /* Allocate image */
549  image = alloc_image ( NULL );
550  if ( ! image ) {
551  rc = -ENOMEM;
552  goto err_alloc_image;
553  }
554 
555  /* Set name */
556  if ( ( rc = image_set_name ( image, name ) ) != 0 )
557  goto err_set_name;
558 
559  /* Set data */
560  if ( ( rc = image_set_data ( image, data, len ) ) != 0 )
561  goto err_set_data;
562 
563  /* Register image */
564  if ( ( rc = register_image ( image ) ) != 0 )
565  goto err_register;
566 
567  /* Drop local reference to image */
568  image_put ( image );
569 
570  return image;
571 
572  err_register:
573  err_set_data:
574  err_set_name:
575  image_put ( image );
576  err_alloc_image:
577  return NULL;
578 }
579 
580 /**
581  * Find argument within image command line
582  *
583  * @v image Image
584  * @v key Argument search key (including trailing delimiter)
585  * @ret value Argument value, or NULL if not found
586  */
587 const char * image_argument ( struct image *image, const char *key ) {
588  const char *cmdline = image->cmdline;
589  const char *search;
590  const char *match;
591  const char *next;
592 
593  /* Find argument */
594  for ( search = cmdline ; search ; search = next ) {
595 
596  /* Find next occurrence, if any */
597  match = strstr ( search, key );
598  if ( ! match )
599  break;
600  next = ( match + strlen ( key ) );
601 
602  /* Check preceding delimiter, if any */
603  if ( ( match == cmdline ) || isspace ( match[-1] ) )
604  return next;
605  }
606 
607  return NULL;
608 }
#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:519
unsigned int flags
Flags.
Definition: image.h:36
static int require_trusted_images_permanent
Prevent changes to image trust requirement.
Definition: image.c:66
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:60
int image_select(struct image *image)
Select image for execution.
Definition: image.c:480
int image_set_uri(struct image *image, struct uri *uri)
Set image URI.
Definition: image.c:120
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
uint32_t next
Next descriptor address.
Definition: myson.h:18
struct image * find_image(const char *name)
Find image by name.
Definition: image.c:312
#define ref_init(refcnt, free)
Initialise a reference counter.
Definition: refcnt.h:64
Error codes.
#define EACCES_UNTRUSTED
Definition: image.c:47
#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:212
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:544
#define EACCES_PERMANENT
Definition: image.c:51
An executable image.
Definition: image.h:24
Character types.
#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:333
static void free_image(struct refcnt *refcnt)
Free executable image.
Definition: image.c:73
unsigned long tmp
Definition: linux_pci.h:53
#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:226
char * strstr(const char *haystack, const char *needle)
Find substring.
Definition: string.c:309
#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_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:252
#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:444
struct list_head images
List of registered images.
Definition: image.c:57
int image_set_name(struct image *image, const char *name)
Set image name.
Definition: image.c:145
#define IMAGE_TRUSTED
Image is trusted.
Definition: image.h:70
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
int isspace(int character)
Check to see if character is a space.
Definition: ctype.c:41
size_t strlen(const char *src)
Get length of string.
Definition: string.c:243
static void image_put(struct image *image)
Decrement reference count on an image.
Definition: image.h:222
int image_set_data(struct image *image, userptr_t data, size_t len)
Set image data.
Definition: image.c:207
struct image * image_find_selected(void)
Find selected image.
Definition: image.c:502
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:294
int image_set_len(struct image *image, size_t len)
Set image length.
Definition: image.c:186
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
const char * image_argument(struct image *image, const char *key)
Find argument within image command line.
Definition: image.c:587
#define syslog(priority, fmt,...)
Write message to system log.
Definition: syslog.h:93
uint8_t data[48]
Additional event data.
Definition: ena.h:22
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:167
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
static int require_trusted_images
Current image trust requirement.
Definition: image.c:63
#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:91
char * name
Name.
Definition: image.h:34
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
String functions.
#define LOG_NOTICE
Notice: normal but significant conditions.
Definition: syslog.h:41
union @382 key
Sense key.
Definition: scsi.h:18
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