iPXE
Data Structures | Defines | 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...

Defines

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

Functions

 FILE_LICENCE (GPL2_OR_LATER_OR_UBDL)
static int have_images (void)
 Test for existence of images.
static struct imagefirst_image (void)
 Retrieve first image.
struct imagealloc_image (struct uri *uri)
 Allocate executable image.
int image_set_uri (struct image *image, struct uri *uri)
 Set image URI.
int image_set_name (struct image *image, const char *name)
 Set image name.
int image_set_cmdline (struct image *image, const char *cmdline)
 Set image command line.
int register_image (struct image *image)
 Register executable image.
void unregister_image (struct image *image)
 Unregister executable image.
struct imagefind_image (const char *name)
 Find image by name.
int image_exec (struct image *image)
 Execute image.
int image_replace (struct image *replacement)
 Set replacement image.
int image_select (struct image *image)
 Select image for execution.
struct imageimage_find_selected (void)
 Find selected image.
int image_set_trust (int require_trusted, int permanent)
 Change image trust requirement.
int image_pixbuf (struct image *image, struct pixel_buffer **pixbuf)
 Create pixel buffer from image.
int image_asn1 (struct image *image, size_t offset, struct asn1_cursor **cursor)
 Extract ASN.1 object from image.
static struct imageimage_get (struct image *image)
 Increment reference count on an image.
static void image_put (struct image *image)
 Decrement reference count on an image.
static void image_clear_cmdline (struct image *image)
 Clear image command line.
static void image_trust (struct image *image)
 Set image as trusted.
static void image_untrust (struct image *image)
 Set image as untrusted.

Variables

struct image __attribute__
struct list_head images
 List of registered images.
struct imagecurrent_image
 Currently-executing image.

Detailed Description

Executable images.

Definition in file image.h.


Define Documentation

#define IMAGE_REGISTERED   0x00001

Image is registered.

Definition at line 64 of file image.h.

Referenced by image_exec(), image_replace(), register_image(), and unregister_image().

#define IMAGE_SELECTED   0x0002

Image is selected for execution.

Definition at line 67 of file image.h.

Referenced by image_find_selected(), image_select(), imgstat(), and register_image().

#define IMAGE_TRUSTED   0x0004

Image is trusted.

Definition at line 70 of file image.h.

Referenced by image_exec(), image_trust(), image_untrust(), and imgstat().

#define IMAGE_AUTO_UNREGISTER   0x0008

Image will be automatically unregistered after execution.

Definition at line 73 of file image.h.

Referenced by image_exec(), imgsingle_exec(), imgstat(), and uriboot().

#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 124 of file image.h.

#define PROBE_NORMAL   02

Normal image probe priority.

Definition at line 129 of file image.h.

#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 137 of file image.h.

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

Executable image type table.

Definition at line 140 of file image.h.

Referenced by image_probe().

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

An executable image type.

Definition at line 143 of file image.h.

#define for_each_image (   image)    list_for_each_entry ( (image), &images, list )
#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 153 of file image.h.

Referenced by imgmulti_exec().


Function Documentation

FILE_LICENCE ( GPL2_OR_LATER_OR_UBDL  )
static int have_images ( void  ) [inline, static]

Test for existence of images.

Return values:
existenceSome images exist

Definition at line 161 of file image.h.

References images, and list_empty.

                                       {
        return ( ! list_empty ( &images ) );
}
static struct image* first_image ( void  ) [static, read]

Retrieve first image.

Return values:
imageImage, or NULL

Definition at line 170 of file image.h.

References images, image::list, and list_first_entry.

Referenced by ipxe().

                                                  {
        return list_first_entry ( &images, struct image, list );
}
struct image* alloc_image ( struct uri uri) [read]

Allocate executable image.

Parameters:
uriURI, or NULL
Return values:
imageExecutable image

Definition at line 90 of file image.c.

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

Referenced by imgdownload(), and initrd_init().

                                               {
        struct image *image;
        int rc;

        /* Allocate image */
        image = zalloc ( sizeof ( *image ) );
        if ( ! image )
                goto err_alloc;

        /* Initialise image */
        ref_init ( &image->refcnt, free_image );
        if ( uri && ( ( rc = image_set_uri ( image, uri ) ) != 0 ) )
                goto err_set_uri;

        return image;

 err_set_uri:
        image_put ( image );
 err_alloc:
        return NULL;
}
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 119 of file image.c.

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().

                                                           {
        const char *name;
        int rc;

        /* Set name, if image does not already have one */
        if ( uri->path && ( ! ( image->name && image->name[0] ) ) ) {
                name = basename ( ( char * ) uri->path );
                if ( ( rc = image_set_name ( image, name ) ) != 0 )
                        return rc;
        }

        /* Update image URI */
        uri_put ( image->uri );
        image->uri = uri_get ( uri );

        return 0;
}
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 144 of file image.c.

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

Referenced by image_set_uri(), imgsingle_exec(), initrd_init(), and register_image().

                                                             {
        char *name_copy;

        /* Duplicate name */
        name_copy = strdup ( name );
        if ( ! name_copy )
                return -ENOMEM;

        /* Replace existing name */
        free ( image->name );
        image->name = name_copy;

        return 0;
}
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 166 of file image.c.

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

Referenced by image_clear_cmdline(), and imgsingle_exec().

                                                                   {

        free ( image->cmdline );
        image->cmdline = NULL;
        if ( cmdline ) {
                image->cmdline = strdup ( cmdline );
                if ( ! image->cmdline )
                        return -ENOMEM;
        }
        return 0;
}
int register_image ( struct image image)

Register executable image.

Parameters:
imageExecutable image
Return values:
rcReturn status code

Definition at line 210 of file image.c.

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

Referenced by asn1_okx(), cmdline_init(), embedded_init(), imgdownload(), initrd_init(), pixbuf_okx(), script_exec(), and test_init().

                                           {
        static unsigned int imgindex = 0;
        char name[8]; /* "imgXXXX" */
        int rc;

        /* Create image name if it doesn't already have one */
        if ( ! image->name ) {
                snprintf ( name, sizeof ( name ), "img%d", imgindex++ );
                if ( ( rc = image_set_name ( image, name ) ) != 0 )
                        return rc;
        }

        /* Avoid ending up with multiple "selected" images on
         * re-registration
         */
        if ( image_find_selected() )
                image->flags &= ~IMAGE_SELECTED;

        /* Add to image list */
        image_get ( image );
        image->flags |= IMAGE_REGISTERED;
        list_add_tail ( &image->list, &images );
        DBGC ( image, "IMAGE %s at [%lx,%lx) registered\n",
               image->name, user_to_phys ( image->data, 0 ),
               user_to_phys ( image->data, image->len ) );

        /* Try to detect image type, if applicable.  Ignore failures,
         * since we expect to handle some unrecognised images
         * (e.g. kernel initrds, multiboot modules, random files
         * provided via our EFI virtual filesystem, etc).
         */
        if ( ! image->type )
                image_probe ( image );

        return 0;
}
void unregister_image ( struct image image)

Unregister executable image.

Parameters:
imageExecutable image

Definition at line 252 of file image.c.

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(), image_exec(), imgfree_exec(), imgverify_exec(), pixbuf_okx(), and script_exec().

                                              {

        /* Do nothing unless image is registered */
        if ( ! ( image->flags & IMAGE_REGISTERED ) )
                return;

        DBGC ( image, "IMAGE %s unregistered\n", image->name );
        list_del ( &image->list );
        image->flags &= ~IMAGE_REGISTERED;
        image_put ( image );
}
struct image* find_image ( const char *  name) [read]

Find image by name.

Parameters:
nameImage name
Return values:
imageExecutable image, or NULL

Definition at line 270 of file image.c.

References image::list, list_for_each_entry, image::name, NULL, and strcmp().

Referenced by imgacquire(), and imgmulti_exec().

                                               {
        struct image *image;

        list_for_each_entry ( image, &images, list ) {
                if ( strcmp ( image->name, name ) == 0 )
                        return image;
        }

        return NULL;
}
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 291 of file image.c.

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_TRUSTED, LOG_ERR, LOG_NOTICE, image::name, NULL, rc, image::replacement, require_trusted_images, strerror(), syslog, image::type, unregister_image(), image::uri, uri_get(), and uri_put().

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

                                       {
        struct image *saved_current_image;
        struct image *replacement = NULL;
        struct uri *old_cwuri;
        int rc;

        /* Sanity check */
        assert ( image->flags & IMAGE_REGISTERED );

        /* Switch current working directory to be that of the image itself */
        old_cwuri = uri_get ( cwuri );
        churi ( image->uri );

        /* Preserve record of any currently-running image */
        saved_current_image = current_image;

        /* Take out a temporary reference to the image.  This allows
         * the image to unregister itself if necessary, without
         * automatically freeing itself.
         */
        current_image = image_get ( image );

        /* Check that this image can be executed */
        if ( ! ( image->type && image->type->exec ) ) {
                rc = -ENOEXEC;
                goto err;
        }

        /* Check that image is trusted (if applicable) */
        if ( require_trusted_images && ! ( image->flags & IMAGE_TRUSTED ) ) {
                DBGC ( image, "IMAGE %s is not trusted\n", image->name );
                rc = -EACCES_UNTRUSTED;
                goto err;
        }

        /* Record boot attempt */
        syslog ( LOG_NOTICE, "Executing \"%s\"\n", image->name );

        /* Try executing the image */
        if ( ( rc = image->type->exec ( image ) ) != 0 ) {
                DBGC ( image, "IMAGE %s could not execute: %s\n",
                       image->name, strerror ( rc ) );
                /* Do not return yet; we still have clean-up to do */
        }

        /* Record result of boot attempt */
        if ( rc == 0 ) {
                syslog ( LOG_NOTICE, "Execution of \"%s\" completed\n",
                         image->name );
        } else {
                syslog ( LOG_ERR, "Execution of \"%s\" failed: %s\n",
                         image->name, strerror ( rc ) );
        }

        /* Pick up replacement image before we drop the original
         * image's temporary reference.  The replacement image must
         * already be registered, so we don't need to hold a temporary
         * reference (which would complicate the tail-recursion).
         */
        replacement = image->replacement;
        if ( replacement )
                assert ( replacement->flags & IMAGE_REGISTERED );

 err:
        /* Unregister image if applicable */
        if ( image->flags & IMAGE_AUTO_UNREGISTER )
                unregister_image ( image );

        /* Debug message for tail-recursion.  Placed here because the
         * image_put() may end up freeing the image.
         */
        if ( replacement ) {
                DBGC ( image, "IMAGE %s replacing self with IMAGE %s\n",
                       image->name, replacement->name );
        }

        /* Drop temporary reference to the original image */
        image_put ( image );

        /* Restore previous currently-running image */
        current_image = saved_current_image;

        /* Reset current working directory */
        churi ( old_cwuri );
        uri_put ( old_cwuri );

        /* Tail-recurse into replacement image, if one exists */
        if ( replacement )
                return image_exec ( replacement );

        return rc;
}
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 393 of file image.c.

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

Referenced by comboot_fetch_kernel(), and imgexec().

                                                {
        struct image *image = current_image;
        int rc;

        /* Sanity check */
        assert ( replacement->flags & IMAGE_REGISTERED );

        /* Fail unless there is a currently-executing image */
        if ( ! image ) {
                rc = -ENOTTY;
                DBGC ( replacement, "IMAGE %s cannot replace non-existent "
                       "image: %s\n", replacement->name, strerror ( rc ) );
                return rc;
        }

        /* Check that the replacement image can be executed */
        if ( ! ( replacement->type && replacement->type->exec ) )
                return -ENOEXEC;

        /* Clear any existing replacement */
        image_put ( image->replacement );

        /* Set replacement */
        image->replacement = image_get ( replacement );
        DBGC ( image, "IMAGE %s will replace self with IMAGE %s\n",
               image->name, replacement->name );

        return 0;
}
int image_select ( struct image image)

Select image for execution.

Parameters:
imageExecutable image
Return values:
rcReturn status code

Definition at line 429 of file image.c.

References ENOEXEC, image_type::exec, image::flags, for_each_image, IMAGE_SELECTED, and image::type.

Referenced by embedded_init(), and imgselect().

                                         {
        struct image *tmp;

        /* Unselect all other images */
        for_each_image ( tmp )
                tmp->flags &= ~IMAGE_SELECTED;

        /* Check that this image can be executed */
        if ( ! ( image->type && image->type->exec ) )
                return -ENOEXEC;

        /* Mark image as selected */
        image->flags |= IMAGE_SELECTED;

        return 0;
}
struct image* image_find_selected ( void  ) [read]

Find selected image.

Return values:
imageExecutable image, or NULL

Definition at line 451 of file image.c.

References image::flags, for_each_image, IMAGE_SELECTED, and NULL.

Referenced by imgsingle_exec(), and register_image().

                                            {
        struct image *image;

        for_each_image ( image ) {
                if ( image->flags & IMAGE_SELECTED )
                        return image;
        }
        return NULL;
}
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 468 of file image.c.

References EACCES_PERMANENT, require_trusted_images, and require_trusted_images_permanent.

Referenced by imgtrust_exec().

                                                           {

        /* Update trust requirement, if permitted to do so */
        if ( ! require_trusted_images_permanent ) {
                require_trusted_images = require_trusted;
                require_trusted_images_permanent = permanent;
        }

        /* Fail if we attempted to change the trust requirement but
         * were not permitted to do so.
         */
        if ( require_trusted_images != require_trusted )
                return -EACCES_PERMANENT;

        return 0;
}
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.

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

Referenced by console_exec(), and pixbuf_okx().

                                                                       {
        int rc;

        /* Check that this image can be used to create a pixel buffer */
        if ( ! ( image->type && image->type->pixbuf ) )
                return -ENOTSUP;

        /* Try creating pixel buffer */
        if ( ( rc = image->type->pixbuf ( image, pixbuf ) ) != 0 ) {
                DBGC ( image, "IMAGE %s could not create pixel buffer: %s\n",
                       image->name, strerror ( rc ) );
                return rc;
        }

        return 0;
}
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 854 of file asn1.c.

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

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

                                               {
        int next;
        int rc;

        /* Sanity check */
        assert ( offset <= image->len );

        /* Check that this image can be used to extract an ASN.1 object */
        if ( ! ( image->type && image->type->asn1 ) )
                return -ENOTSUP;

        /* Try creating ASN.1 cursor */
        next = image->type->asn1 ( image, offset, cursor );
        if ( next < 0 ) {
                rc = next;
                DBGC ( image, "IMAGE %s could not extract ASN.1 object: %s\n",
                       image->name, strerror ( rc ) );
                return rc;
        }

        return next;
}
static struct image* image_get ( struct image image) [static, read]

Increment reference count on an image.

Parameters:
imageImage
Return values:
imageImage

Definition at line 196 of file image.h.

References ref_get, and image::refcnt.

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

                                                               {
        ref_get ( &image->refcnt );
        return image;
}
static void image_put ( struct image image) [inline, static]

Decrement reference count on an image.

Parameters:
imageImage

Definition at line 206 of file image.h.

References ref_put, and image::refcnt.

Referenced by alloc_image(), cmdline_init(), downloader_free(), efi_file_close(), free_image(), image_exec(), image_replace(), imgdownload(), initrd_init(), and unregister_image().

                                                     {
        ref_put ( &image->refcnt );
}
static void image_clear_cmdline ( struct image image) [inline, static]

Clear image command line.

Parameters:
imageImage

Definition at line 215 of file image.h.

References image_set_cmdline(), and NULL.

                                                               {
        image_set_cmdline ( image, NULL );
}
static void image_trust ( struct image image) [inline, static]

Set image as trusted.

Parameters:
imageImage

Definition at line 224 of file image.h.

References image::flags, and IMAGE_TRUSTED.

Referenced by imgverify().

                                                       {
        image->flags |= IMAGE_TRUSTED;
}
static void image_untrust ( struct image image) [inline, static]

Set image as untrusted.

Parameters:
imageImage

Definition at line 233 of file image.h.

References image::flags, and IMAGE_TRUSTED.

Referenced by imgverify().

                                                         {
        image->flags &= ~IMAGE_TRUSTED;
}

Variable Documentation

struct list_head images

List of registered images.

Definition at line 56 of file image.c.

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

Currently-executing image.

Definition at line 59 of file image.c.

Referenced by goto_exec(), image_exec(), and image_replace().