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