iPXE
Data Structures | Macros | Functions | Variables
image.h File Reference

Executable images. More...

#include <ipxe/tables.h>
#include <ipxe/list.h>
#include <ipxe/uaccess.h>
#include <ipxe/refcnt.h>

Go to the source code of this file.

Data Structures

struct  image
 An executable image. More...
 
struct  image_type
 An executable image type. More...
 
struct  image_tag
 An image tag. More...
 

Macros

#define IMAGE_REGISTERED   0x0001
 Image is registered. More...
 
#define IMAGE_TRUSTED   0x0002
 Image is trusted. More...
 
#define IMAGE_AUTO_UNREGISTER   0x0004
 Image will be automatically unregistered after execution. More...
 
#define IMAGE_HIDDEN   0x0008
 Image will be hidden from enumeration. More...
 
#define PROBE_MULTIBOOT   01
 Multiboot image probe priority. More...
 
#define PROBE_NORMAL   02
 Normal image probe priority. More...
 
#define PROBE_PXE   03
 PXE image probe priority. More...
 
#define IMAGE_TYPES   __table ( struct image_type, "image_types" )
 Executable image type table. More...
 
#define __image_type(probe_order)   __table_entry ( IMAGE_TYPES, probe_order )
 An executable image type. More...
 
#define IMAGE_TAGS   __table ( struct image_tag, "image_tags" )
 Image tag table. More...
 
#define __image_tag   __table_entry ( IMAGE_TAGS, 01 )
 An image tag. More...
 
#define for_each_image(image)   list_for_each_entry ( (image), &images, list )
 Iterate over all registered images. More...
 
#define for_each_image_safe(image, tmp)   list_for_each_entry_safe ( (image), (tmp), &images, list )
 Iterate over all registered images, safe against deletion. More...
 

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
 
static struct imagefirst_image (void)
 Retrieve first image. More...
 
struct imagealloc_image (struct uri *uri)
 Allocate executable image. More...
 
int image_set_uri (struct image *image, struct uri *uri)
 Set image URI. More...
 
int image_set_name (struct image *image, const char *name)
 Set image name. More...
 
int image_set_cmdline (struct image *image, const char *cmdline)
 Set image command line. More...
 
int image_set_len (struct image *image, size_t len)
 Set image length. More...
 
int image_set_data (struct image *image, userptr_t data, size_t len)
 Set image data. More...
 
int register_image (struct image *image)
 Register executable image. More...
 
void unregister_image (struct image *image)
 Unregister executable image. More...
 
struct imagefind_image (const char *name)
 Find image by name. More...
 
struct imagefind_image_tag (struct image_tag *tag)
 Find image by tag. More...
 
int image_exec (struct image *image)
 Execute image. More...
 
int image_replace (struct image *replacement)
 Set replacement image. More...
 
int image_select (struct image *image)
 Select image for execution. More...
 
int image_set_trust (int require_trusted, int permanent)
 Change image trust requirement. More...
 
struct imageimage_memory (const char *name, userptr_t data, size_t len)
 Create registered image from block of memory. More...
 
const char * image_argument (struct image *image, const char *key)
 Find argument within image command line. More...
 
int image_pixbuf (struct image *image, struct pixel_buffer **pixbuf)
 Create pixel buffer from image. More...
 
int image_asn1 (struct image *image, size_t offset, struct asn1_cursor **cursor)
 Extract ASN.1 object from image. More...
 
int image_extract (struct image *image, const char *name, struct image **extracted)
 Extract archive image. More...
 
int image_extract_exec (struct image *image)
 Extract and execute image. More...
 
static struct imageimage_get (struct image *image)
 Increment reference count on an image. More...
 
static void image_put (struct image *image)
 Decrement reference count on an image. More...
 
static void image_clear_cmdline (struct image *image)
 Clear image command line. More...
 
static void image_trust (struct image *image)
 Set image as trusted. More...
 
static void image_untrust (struct image *image)
 Set image as untrusted. More...
 
static void image_hide (struct image *image)
 Mark image as hidden. More...
 
static struct imageimage_tag (struct image *image, struct image_tag *tag)
 Tag image. More...
 

Variables

struct image __attribute__
 
struct list_head images
 List of registered images. More...
 
struct image_tag current_image
 
struct image_tag selected_image
 

Detailed Description

Executable images.

Definition in file image.h.

Macro Definition Documentation

◆ IMAGE_REGISTERED

#define IMAGE_REGISTERED   0x0001

Image is registered.

Definition at line 64 of file image.h.

◆ IMAGE_TRUSTED

#define IMAGE_TRUSTED   0x0002

Image is trusted.

Definition at line 67 of file image.h.

◆ IMAGE_AUTO_UNREGISTER

#define IMAGE_AUTO_UNREGISTER   0x0004

Image will be automatically unregistered after execution.

Definition at line 70 of file image.h.

◆ IMAGE_HIDDEN

#define IMAGE_HIDDEN   0x0008

Image will be hidden from enumeration.

Definition at line 73 of file image.h.

◆ PROBE_MULTIBOOT

#define PROBE_MULTIBOOT   01

Multiboot image probe priority.

Multiboot images are also valid executables in another format (e.g. ELF), so we must perform the multiboot probe first.

Definition at line 132 of file image.h.

◆ PROBE_NORMAL

#define PROBE_NORMAL   02

Normal image probe priority.

Definition at line 137 of file image.h.

◆ PROBE_PXE

#define PROBE_PXE   03

PXE image probe priority.

PXE images have no signature checks, so will claim all image files. They must therefore be tried last in the probe order list.

Definition at line 145 of file image.h.

◆ IMAGE_TYPES

#define IMAGE_TYPES   __table ( struct image_type, "image_types" )

Executable image type table.

Definition at line 148 of file image.h.

◆ __image_type

#define __image_type (   probe_order)    __table_entry ( IMAGE_TYPES, probe_order )

An executable image type.

Definition at line 151 of file image.h.

◆ IMAGE_TAGS

#define IMAGE_TAGS   __table ( struct image_tag, "image_tags" )

Image tag table.

Definition at line 162 of file image.h.

◆ __image_tag

struct image_tag current_image __image_tag   __table_entry ( IMAGE_TAGS, 01 )

An image tag.

Currently-executing image.

Definition at line 165 of file image.h.

◆ for_each_image

#define for_each_image (   image)    list_for_each_entry ( (image), &images, list )

Iterate over all registered images.

Definition at line 172 of file image.h.

◆ for_each_image_safe

#define for_each_image_safe (   image,
  tmp 
)    list_for_each_entry_safe ( (image), (tmp), &images, list )

Iterate over all registered images, safe against deletion.

Definition at line 176 of file image.h.

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )

◆ first_image()

static struct image* first_image ( void  )
inlinestatic

Retrieve first image.

Return values
imageImage, or NULL

Definition at line 184 of file image.h.

184  {
185  return list_first_entry ( &images, struct image, list );
186 }
An executable image.
Definition: image.h:24
#define list_first_entry(list, type, member)
Get the container of the first entry in a list.
Definition: list.h:333
struct list_head images
List of registered images.
Definition: image.c:57

References images, image::list, and list_first_entry.

Referenced by ipxe().

◆ alloc_image()

struct image* alloc_image ( struct uri uri)

Allocate executable image.

Parameters
uriURI, or NULL
Return values
imageExecutable image

Definition at line 103 of file image.c.

103  {
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 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
int image_set_uri(struct image *image, struct uri *uri)
Set image URI.
Definition: image.c:132
#define ref_init(refcnt, free)
Initialise a reference counter.
Definition: refcnt.h:64
An executable image.
Definition: image.h:24
static void free_image(struct refcnt *refcnt)
Free executable image.
Definition: image.c:80
void * zalloc(size_t size)
Allocate cleared memory.
Definition: malloc.c:624
static void image_put(struct image *image)
Decrement reference count on an image.
Definition: image.h:228
A Uniform Resource Identifier.
Definition: uri.h:64
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
struct refcnt refcnt
Reference count.
Definition: image.h:26

References free_image(), image_put(), image_set_uri(), NULL, rc, ref_init, image::refcnt, and zalloc().

Referenced by image_extract(), image_memory(), and imgdownload().

◆ image_set_uri()

int image_set_uri ( struct image image,
struct uri uri 
)

Set image URI.

Parameters
imageImage
uriNew image URI
Return values
rcReturn status code

Definition at line 132 of file image.c.

132  {
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 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
const char * name
Definition: ath9k_hw.c:1984
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
An executable image.
Definition: image.h:24
const char * path
Path (after URI decoding)
Definition: uri.h:80
char * basename(char *path)
Return base name from path.
Definition: basename.c:42
int image_set_name(struct image *image, const char *name)
Set image name.
Definition: image.c:157
struct uri * uri
URI of image.
Definition: image.h:32
A Uniform Resource Identifier.
Definition: uri.h:64
char * name
Name.
Definition: image.h:34

References basename(), image_set_name(), image::name, name, uri::path, rc, image::uri, uri_get(), and uri_put().

Referenced by alloc_image(), and downloader_vredirect().

◆ image_set_name()

int image_set_name ( struct image image,
const char *  name 
)

Set image name.

Parameters
imageImage
nameNew image name
Return values
rcReturn status code

Definition at line 157 of file image.c.

157  {
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 }
const char * name
Definition: ath9k_hw.c:1984
An executable image.
Definition: image.h:24
#define ENOMEM
Not enough space.
Definition: errno.h:534
static void(* free)(struct refcnt *refcnt))
Definition: refcnt.h:54
char * strdup(const char *src)
Duplicate string.
Definition: string.c:380
char * name
Name.
Definition: image.h:34

References ENOMEM, free, image::name, name, and strdup().

Referenced by image_extract(), image_memory(), image_set_uri(), imgsingle_exec(), and register_image().

◆ image_set_cmdline()

int image_set_cmdline ( struct image image,
const char *  cmdline 
)

Set image command line.

Parameters
imageImage
cmdlineNew image command line, or NULL
Return values
rcReturn status code

Definition at line 179 of file image.c.

179  {
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 }
An executable image.
Definition: image.h:24
char * cmdline
Command line to pass to image.
Definition: image.h:39
#define ENOMEM
Not enough space.
Definition: errno.h:534
static void(* free)(struct refcnt *refcnt))
Definition: refcnt.h:54
char * strdup(const char *src)
Duplicate string.
Definition: string.c:380
uint32_t cmdline
Definition: multiboot.h:16
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321

References cmdline, image::cmdline, ENOMEM, free, NULL, and strdup().

Referenced by image_clear_cmdline(), image_extract_exec(), and imgsingle_exec().

◆ image_set_len()

int image_set_len ( struct image image,
size_t  len 
)

Set image length.

Parameters
imageImage
lenLength of image data
Return values
rcReturn status code

Definition at line 198 of file image.c.

198  {
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 }
userptr_t data
Raw file image.
Definition: image.h:41
An executable image.
Definition: image.h:24
#define ENOMEM
Not enough space.
Definition: errno.h:534
userptr_t urealloc(userptr_t userptr, size_t new_size)
Reallocate external memory.
size_t len
Length of raw file image.
Definition: image.h:43
uint32_t len
Length.
Definition: ena.h:14
unsigned long userptr_t
A pointer to a user buffer.
Definition: uaccess.h:33

References image::data, ENOMEM, len, image::len, and urealloc().

Referenced by gzip_extract(), image_set_data(), and zlib_deflate().

◆ image_set_data()

int image_set_data ( struct image image,
userptr_t  data,
size_t  len 
)

Set image data.

Parameters
imageImage
dataImage data
lenLength of image data
Return values
rcReturn status code

Definition at line 219 of file image.c.

219  {
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 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
userptr_t data
Raw file image.
Definition: image.h:41
An executable image.
Definition: image.h:24
int image_set_len(struct image *image, size_t len)
Set image length.
Definition: image.c:198
uint32_t len
Length.
Definition: ena.h:14
uint8_t data[48]
Additional event data.
Definition: ena.h:22
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.

References data, image::data, image_set_len(), len, memcpy_user(), and rc.

Referenced by image_memory().

◆ register_image()

int register_image ( struct image image)

Register executable image.

Parameters
imageExecutable image
Return values
rcReturn status code

Definition at line 264 of file image.c.

264  {
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 }
unsigned int flags
Flags.
Definition: image.h:36
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
const char * name
Definition: ath9k_hw.c:1984
userptr_t data
Raw file image.
Definition: image.h:41
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.
Definition: image.h:24
static int image_probe(struct image *image)
Determine image type.
Definition: image.c:238
#define list_add_tail(new, head)
Add a new entry to the tail of a list.
Definition: list.h:93
#define IMAGE_REGISTERED
Image is registered.
Definition: image.h:64
size_t len
Length of raw file image.
Definition: image.h:43
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
int snprintf(char *buf, size_t size, const char *fmt,...)
Write a formatted string to a buffer.
Definition: vsprintf.c:382
struct list_head list
List of registered images.
Definition: image.h:29
char * name
Name.
Definition: image.h:34

References image::data, DBGC, image::flags, image_get(), image_probe(), IMAGE_REGISTERED, image_set_name(), images, image::len, image::list, list_add_tail, image::name, name, rc, snprintf(), image::type, and user_to_phys().

Referenced by asn1_okx(), cmdline_init(), efi_cmdline_init(), efi_image_exec(), embedded_init(), image_exec(), image_extract(), image_memory(), imgdownload(), pixbuf_okx(), and test_init().

◆ unregister_image()

void unregister_image ( struct image image)

Unregister executable image.

Parameters
imageExecutable image

Definition at line 300 of file image.c.

300  {
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 }
unsigned int flags
Flags.
Definition: image.h:36
#define DBGC(...)
Definition: compiler.h:505
An executable image.
Definition: image.h:24
#define list_del(list)
Delete an entry from a list.
Definition: list.h:119
#define IMAGE_REGISTERED
Image is registered.
Definition: image.h:64
static void image_put(struct image *image)
Decrement reference count on an image.
Definition: image.h:228
struct list_head list
List of registered images.
Definition: image.h:29
char * name
Name.
Definition: image.h:34

References DBGC, image::flags, image_put(), IMAGE_REGISTERED, image::list, list_del, and image::name.

Referenced by asn1_okx(), bzimage_exec(), cert_exec(), com32_exec_loop(), comboot_exec_loop(), console_exec(), efi_image_exec(), gzip_okx(), image_exec(), image_extract(), image_extract_exec(), imgextract_exec(), imgfree_exec(), imgverify_exec(), pixbuf_okx(), and zlib_okx().

◆ find_image()

struct image* find_image ( const char *  name)

Find image by name.

Parameters
nameImage name
Return values
imageExecutable image, or NULL

Definition at line 318 of file image.c.

318  {
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 }
const char * name
Definition: ath9k_hw.c:1984
An executable image.
Definition: image.h:24
#define for_each_image(image)
Iterate over all registered images.
Definition: image.h:172
int strcmp(const char *first, const char *second)
Compare strings.
Definition: string.c:173
char * name
Name.
Definition: image.h:34
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321

References for_each_image, image::name, name, NULL, and strcmp().

Referenced by imgacquire(), and imgmulti_exec().

◆ find_image_tag()

struct image* find_image_tag ( struct image_tag tag)

Find image by tag.

Parameters
tagImage tag
Return values
imageExecutable image, or NULL

Definition at line 335 of file image.c.

335  {
336  struct image *image;
337 
338  for_each_image ( image ) {
339  if ( tag->image == image )
340  return image;
341  }
342 
343  return NULL;
344 }
An executable image.
Definition: image.h:24
#define for_each_image(image)
Iterate over all registered images.
Definition: image.h:172
uint64_t tag
Identity tag.
Definition: edd.h:30
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321

References for_each_image, NULL, and tag.

Referenced by efi_file_open(), efi_image_exec(), imgsingle_exec(), and shim_exec().

◆ image_exec()

int image_exec ( struct image image)

Execute image.

Parameters
imageExecutable image
Return values
rcReturn status code

The image must already be registered. Note that executing an image may cause it to unregister itself. The caller must therefore assume that the image pointer becomes invalid.

Definition at line 356 of file image.c.

356  {
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 }
unsigned int flags
Flags.
Definition: image.h:36
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
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
#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
#define DBGC(...)
Definition: compiler.h:505
An executable image.
Definition: image.h:24
#define LOG_ERR
Error: error conditions.
Definition: syslog.h:35
#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
int image_exec(struct image *image)
Execute image.
Definition: image.c:356
struct image_tag current_image
void churi(struct uri *uri)
Change working URI.
Definition: cwuri.c:45
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
#define IMAGE_REGISTERED
Image is registered.
Definition: image.h:64
int register_image(struct image *image)
Register executable image.
Definition: image.c:264
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
#define IMAGE_TRUSTED
Image is trusted.
Definition: image.h:67
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:228
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:300
#define syslog(priority, fmt,...)
Write message to system log.
Definition: syslog.h:93
struct image * replacement
Replacement image.
Definition: image.h:60
A Uniform Resource Identifier.
Definition: uri.h:64
static int require_trusted_images
Current image trust requirement.
Definition: image.c:70
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
char * name
Name.
Definition: image.h:34
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
#define LOG_NOTICE
Notice: normal but significant conditions.
Definition: syslog.h:41

References assert(), churi(), current_image, cwuri, DBGC, EACCES_UNTRUSTED, ENOEXEC, image_type::exec, image::flags, IMAGE_AUTO_UNREGISTER, image_exec(), image_get(), image_put(), IMAGE_REGISTERED, image_tag(), IMAGE_TRUSTED, LOG_ERR, LOG_NOTICE, image::name, NULL, rc, register_image(), image::replacement, require_trusted_images, strerror(), syslog, image::type, unregister_image(), image::uri, uri_get(), and uri_put().

Referenced by image_exec(), image_extract_exec(), imgexec(), ipxe(), and uriboot().

◆ image_replace()

int image_replace ( struct image replacement)

Set replacement image.

Parameters
replacementReplacement image
Return values
rcReturn status code

The replacement image must already be registered, and must remain registered until the currently-executing image returns.

Definition at line 467 of file image.c.

467  {
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 }
unsigned int flags
Flags.
Definition: image.h:36
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
#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
#define DBGC(...)
Definition: compiler.h:505
An executable image.
Definition: image.h:24
struct image * image
Image (weak reference, nullified when image is freed)
Definition: image.h:158
int(* exec)(struct image *image)
Execute image.
Definition: image.h:94
struct image_tag current_image
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
#define IMAGE_REGISTERED
Image is registered.
Definition: image.h:64
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
static void image_put(struct image *image)
Decrement reference count on an image.
Definition: image.h:228
#define ENOTTY
Inappropriate I/O control operation.
Definition: errno.h:594
struct image * replacement
Replacement image.
Definition: image.h:60
char * name
Name.
Definition: image.h:34

References assert(), current_image, DBGC, ENOEXEC, ENOTTY, image_type::exec, image::flags, image_tag::image, image_get(), image_put(), IMAGE_REGISTERED, image::name, rc, image::replacement, strerror(), and image::type.

Referenced by comboot_fetch_kernel(), and imgexec().

◆ image_select()

int image_select ( struct image image)

Select image for execution.

Parameters
imageExecutable image
Return values
rcReturn status code

Definition at line 503 of file image.c.

503  {
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 }
struct image_tag selected_image
#define ENOEXEC
Exec format error.
Definition: errno.h:519
struct image_type * type
Image type, if known.
Definition: image.h:46
An executable image.
Definition: image.h:24
int(* exec)(struct image *image)
Execute image.
Definition: image.h:94
static struct image * image_tag(struct image *image, struct image_tag *tag)
Tag image.
Definition: image.h:275

References ENOEXEC, image_type::exec, image_tag(), selected_image, and image::type.

Referenced by embedded_init(), and imgselect().

◆ image_set_trust()

int image_set_trust ( int  require_trusted,
int  permanent 
)

Change image trust requirement.

Parameters
require_trustedRequire trusted images
permanentMake trust requirement permanent
Return values
rcReturn status code

Definition at line 522 of file image.c.

522  {
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 }
static int require_trusted_images_permanent
Prevent changes to image trust requirement.
Definition: image.c:73
#define EACCES_PERMANENT
Definition: image.c:51
static int require_trusted_images
Current image trust requirement.
Definition: image.c:70

References EACCES_PERMANENT, require_trusted_images, and require_trusted_images_permanent.

Referenced by imgtrust_exec().

◆ image_memory()

struct image* image_memory ( const char *  name,
userptr_t  data,
size_t  len 
)

Create registered image from block of memory.

Parameters
nameName
dataImage data
lenLength
Return values
imageImage, or NULL on error

Definition at line 547 of file image.c.

547  {
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 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
const char * name
Definition: ath9k_hw.c:1984
An executable image.
Definition: image.h:24
#define ENOMEM
Not enough space.
Definition: errno.h:534
int register_image(struct image *image)
Register executable image.
Definition: image.c:264
int image_set_name(struct image *image, const char *name)
Set image name.
Definition: image.c:157
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
uint32_t len
Length.
Definition: ena.h:14
uint8_t data[48]
Additional event data.
Definition: ena.h:22
struct image * alloc_image(struct uri *uri)
Allocate executable image.
Definition: image.c:103
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321

References alloc_image(), data, ENOMEM, image_put(), image_set_data(), image_set_name(), len, name, NULL, rc, and register_image().

Referenced by efi_autoexec_startup(), gzip_okx(), imgmem(), initrd_init(), and zlib_okx().

◆ image_argument()

const char* image_argument ( struct image image,
const char *  key 
)

Find argument within image command line.

Parameters
imageImage
keyArgument search key (including trailing delimiter)
Return values
valueArgument value, or NULL if not found

Definition at line 590 of file image.c.

590  {
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 }
uint32_t next
Next descriptor address.
Definition: myson.h:18
An executable image.
Definition: image.h:24
char * cmdline
Command line to pass to image.
Definition: image.h:39
char * strstr(const char *haystack, const char *needle)
Find substring.
Definition: string.c:309
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
uint32_t cmdline
Definition: multiboot.h:16
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
union @382 key
Sense key.
Definition: crypto.h:284

References cmdline, image::cmdline, isspace(), key, next, NULL, strlen(), and strstr().

Referenced by bzimage_parse_cmdline(), and cpio_parse_cmdline().

◆ image_pixbuf()

int image_pixbuf ( struct image image,
struct pixel_buffer **  pixbuf 
)

Create pixel buffer from image.

Parameters
imageImage
pixbufPixel buffer to fill in
Return values
rcReturn status code

Definition at line 97 of file pixbuf.c.

97  {
98  int rc;
99 
100  /* Check that this image can be used to create a pixel buffer */
101  if ( ! ( image->type && image->type->pixbuf ) )
102  return -ENOTSUP;
103 
104  /* Try creating pixel buffer */
105  if ( ( rc = image->type->pixbuf ( image, pixbuf ) ) != 0 ) {
106  DBGC ( image, "IMAGE %s could not create pixel buffer: %s\n",
107  image->name, strerror ( rc ) );
108  return rc;
109  }
110 
111  return 0;
112 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
struct image_type * type
Image type, if known.
Definition: image.h:46
#define DBGC(...)
Definition: compiler.h:505
An executable image.
Definition: image.h:24
#define ENOTSUP
Operation not supported.
Definition: errno.h:589
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
int(* pixbuf)(struct image *image, struct pixel_buffer **pixbuf)
Create pixel buffer from image.
Definition: image.h:102
char * name
Name.
Definition: image.h:34

References DBGC, ENOTSUP, image::name, image_type::pixbuf, rc, strerror(), and image::type.

Referenced by console_exec(), and pixbuf_okx().

◆ image_asn1()

int image_asn1 ( struct image image,
size_t  offset,
struct asn1_cursor **  cursor 
)

Extract ASN.1 object from image.

Parameters
imageImage
offsetOffset within image
cursorASN.1 cursor to fill in
Return values
nextOffset to next image, or negative error

The caller is responsible for eventually calling free() on the allocated ASN.1 cursor.

Definition at line 880 of file asn1.c.

881  {
882  int next;
883  int rc;
884 
885  /* Sanity check */
886  assert ( offset <= image->len );
887 
888  /* Check that this image can be used to extract an ASN.1 object */
889  if ( ! ( image->type && image->type->asn1 ) )
890  return -ENOTSUP;
891 
892  /* Try creating ASN.1 cursor */
893  next = image->type->asn1 ( image, offset, cursor );
894  if ( next < 0 ) {
895  rc = next;
896  DBGC ( image, "IMAGE %s could not extract ASN.1 object: %s\n",
897  image->name, strerror ( rc ) );
898  return rc;
899  }
900 
901  return next;
902 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
uint32_t next
Next descriptor address.
Definition: myson.h:18
struct image_type * type
Image type, if known.
Definition: image.h:46
#define DBGC(...)
Definition: compiler.h:505
An executable image.
Definition: image.h:24
#define ENOTSUP
Operation not supported.
Definition: errno.h:589
assert((readw(&hdr->flags) &(GTF_reading|GTF_writing))==0)
static userptr_t size_t offset
Offset of the first segment within the content.
Definition: deflate.h:259
int(* asn1)(struct image *image, size_t offset, struct asn1_cursor **cursor)
Extract ASN.1 object from image.
Definition: image.h:114
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
uint32_t len
Length.
Definition: ena.h:14
char * name
Name.
Definition: image.h:34

References image_type::asn1, assert(), DBGC, ENOTSUP, len, image::name, next, offset, rc, strerror(), and image::type.

Referenced by asn1_okx(), image_x509(), and imgverify().

◆ image_extract()

int image_extract ( struct image image,
const char *  name,
struct image **  extracted 
)

Extract archive image.

Parameters
imageImage
nameExtracted image name
extractedExtracted image to fill in
Return values
rcReturn status code

Definition at line 44 of file archive.c.

45  {
46  char *dot;
47  int rc;
48 
49  /* Check that this image can be used to extract an archive image */
50  if ( ! ( image->type && image->type->extract ) ) {
51  rc = -ENOTSUP;
52  goto err_unsupported;
53  }
54 
55  /* Allocate new image */
56  *extracted = alloc_image ( image->uri );
57  if ( ! *extracted ) {
58  rc = -ENOMEM;
59  goto err_alloc;
60  }
61 
62  /* Set image name */
63  if ( ( rc = image_set_name ( *extracted,
64  ( name ? name : image->name ) ) ) != 0 ) {
65  goto err_set_name;
66  }
67 
68  /* Strip any archive or compression suffix from implicit name */
69  if ( ( ! name ) && ( (*extracted)->name ) &&
70  ( ( dot = strrchr ( (*extracted)->name, '.' ) ) != NULL ) ) {
71  *dot = '\0';
72  }
73 
74  /* Try extracting archive image */
75  if ( ( rc = image->type->extract ( image, *extracted ) ) != 0 ) {
76  DBGC ( image, "IMAGE %s could not extract image: %s\n",
77  image->name, strerror ( rc ) );
78  goto err_extract;
79  }
80 
81  /* Register image */
82  if ( ( rc = register_image ( *extracted ) ) != 0 )
83  goto err_register;
84 
85  /* Propagate trust flag */
86  if ( image->flags & IMAGE_TRUSTED )
87  image_trust ( *extracted );
88 
89  /* Drop local reference to image */
90  image_put ( *extracted );
91 
92  return 0;
93 
94  unregister_image ( *extracted );
95  err_register:
96  err_extract:
97  err_set_name:
98  image_put ( *extracted );
99  err_alloc:
100  err_unsupported:
101  return rc;
102 }
unsigned int flags
Flags.
Definition: image.h:36
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
const char * name
Definition: ath9k_hw.c:1984
char * strrchr(const char *src, int character)
Find rightmost character within a string.
Definition: string.c:289
struct image_type * type
Image type, if known.
Definition: image.h:46
#define DBGC(...)
Definition: compiler.h:505
An executable image.
Definition: image.h:24
#define ENOTSUP
Operation not supported.
Definition: errno.h:589
#define ENOMEM
Not enough space.
Definition: errno.h:534
int register_image(struct image *image)
Register executable image.
Definition: image.c:264
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
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
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:228
int(* extract)(struct image *image, struct image *extracted)
Extract archive image.
Definition: image.h:123
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:300
static void image_trust(struct image *image)
Set image as trusted.
Definition: image.h:246
struct image * alloc_image(struct uri *uri)
Allocate executable image.
Definition: image.c:103
char * name
Name.
Definition: image.h:34
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321

References alloc_image(), DBGC, ENOMEM, ENOTSUP, image_type::extract, image::flags, image_put(), image_set_name(), image_trust(), IMAGE_TRUSTED, image::name, name, NULL, rc, register_image(), strerror(), strrchr(), image::type, unregister_image(), and image::uri.

Referenced by gzip_okx(), image_extract_exec(), imgextract(), and zlib_okx().

◆ image_extract_exec()

int image_extract_exec ( struct image image)

Extract and execute image.

Parameters
imageImage
Return values
rcReturn status code

Definition at line 110 of file archive.c.

110  {
111  struct image *extracted;
112  int rc;
113 
114  /* Extract image */
115  if ( ( rc = image_extract ( image, NULL, &extracted ) ) != 0 )
116  goto err_extract;
117 
118  /* Set image command line */
119  if ( ( rc = image_set_cmdline ( extracted, image->cmdline ) ) != 0 )
120  goto err_set_cmdline;
121 
122  /* Set auto-unregister flag */
123  extracted->flags |= IMAGE_AUTO_UNREGISTER;
124 
125  /* Tail-recurse into extracted image */
126  return image_exec ( extracted );
127 
128  err_set_cmdline:
129  unregister_image ( extracted );
130  err_extract:
131  return rc;
132 }
unsigned int flags
Flags.
Definition: image.h:36
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
An executable image.
Definition: image.h:24
#define IMAGE_AUTO_UNREGISTER
Image will be automatically unregistered after execution.
Definition: image.h:70
char * cmdline
Command line to pass to image.
Definition: image.h:39
int image_exec(struct image *image)
Execute image.
Definition: image.c:356
int image_extract(struct image *image, const char *name, struct image **extracted)
Extract archive image.
Definition: archive.c:44
void unregister_image(struct image *image)
Unregister executable image.
Definition: image.c:300
int image_set_cmdline(struct image *image, const char *cmdline)
Set image command line.
Definition: image.c:179
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321

References image::cmdline, image::flags, IMAGE_AUTO_UNREGISTER, image_exec(), image_extract(), image_set_cmdline(), NULL, rc, and unregister_image().

◆ image_get()

static struct image* image_get ( struct image image)
inlinestatic

Increment reference count on an image.

Parameters
imageImage
Return values
imageImage

Definition at line 218 of file image.h.

218  {
219  ref_get ( &image->refcnt );
220  return image;
221 }
An executable image.
Definition: image.h:24
#define ref_get(refcnt)
Get additional reference to object.
Definition: refcnt.h:92
struct refcnt refcnt
Reference count.
Definition: image.h:26

References ref_get, and image::refcnt.

Referenced by bzimage_exec(), create_downloader(), efi_file_open_image(), image_exec(), image_replace(), and register_image().

◆ image_put()

static void image_put ( struct image image)
inlinestatic

Decrement reference count on an image.

Parameters
imageImage

Definition at line 228 of file image.h.

228  {
229  ref_put ( &image->refcnt );
230 }
An executable image.
Definition: image.h:24
#define ref_put(refcnt)
Drop reference to object.
Definition: refcnt.h:106
struct refcnt refcnt
Reference count.
Definition: image.h:26

References ref_put, and image::refcnt.

Referenced by alloc_image(), cmdline_init(), downloader_free(), efi_cmdline_init(), efi_file_free(), free_image(), image_exec(), image_extract(), image_memory(), image_replace(), imgdownload(), and unregister_image().

◆ image_clear_cmdline()

static void image_clear_cmdline ( struct image image)
inlinestatic

Clear image command line.

Parameters
imageImage

Definition at line 237 of file image.h.

237  {
239 }
int image_set_cmdline(struct image *image, const char *cmdline)
Set image command line.
Definition: image.c:179
An executable image.
Definition: image.h:24
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321

References image_set_cmdline(), and NULL.

◆ image_trust()

static void image_trust ( struct image image)
inlinestatic

Set image as trusted.

Parameters
imageImage

Definition at line 246 of file image.h.

246  {
248 }
unsigned int flags
Flags.
Definition: image.h:36
An executable image.
Definition: image.h:24
#define IMAGE_TRUSTED
Image is trusted.
Definition: image.h:67

References image::flags, and IMAGE_TRUSTED.

Referenced by embedded_init(), image_extract(), and imgverify().

◆ image_untrust()

static void image_untrust ( struct image image)
inlinestatic

Set image as untrusted.

Parameters
imageImage

Definition at line 255 of file image.h.

255  {
257 }
unsigned int flags
Flags.
Definition: image.h:36
An executable image.
Definition: image.h:24
#define IMAGE_TRUSTED
Image is trusted.
Definition: image.h:67

References image::flags, and IMAGE_TRUSTED.

Referenced by imgverify().

◆ image_hide()

static void image_hide ( struct image image)
inlinestatic

Mark image as hidden.

Parameters
imageImage

Definition at line 264 of file image.h.

264  {
266 }
unsigned int flags
Flags.
Definition: image.h:36
An executable image.
Definition: image.h:24
#define IMAGE_HIDDEN
Image will be hidden from enumeration.
Definition: image.h:73

References image::flags, and IMAGE_HIDDEN.

Referenced by shim().

◆ image_tag()

static struct image* image_tag ( struct image image,
struct image_tag tag 
)
inlinestatic

Tag image.

Parameters
imageImage
tagImage tag
Return values
prevPrevious tagged image (if any)

Definition at line 275 of file image.h.

276  {
277  struct image *prev = tag->image;
278 
279  tag->image = image;
280  return prev;
281 }
An executable image.
Definition: image.h:24
uint64_t tag
Identity tag.
Definition: edd.h:30

References tag.

Referenced by image_exec(), image_select(), and shim().

Variable Documentation

◆ __attribute__

◆ images

struct list_head images

List of registered images.

Definition at line 57 of file image.c.

Referenced by first_image(), initrd_dump(), initrd_reshuffle(), initrd_squash_high(), initrd_swap(), and register_image().

◆ current_image

struct image_tag current_image

◆ selected_image

struct image_tag selected_image