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

Macros
#define	IMAGE_REGISTERED   0x00001
	Image is registered. More...
#define	IMAGE_SELECTED   0x0002
	Image is selected for execution. More...
#define	IMAGE_TRUSTED   0x0004
	Image is trusted. More...
#define	IMAGE_AUTO_UNREGISTER   0x0008
	Image will be automatically unregistered after execution. 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	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 int	have_images (void)
	Test for existence of images. More...
static struct image *	first_image (void)
	Retrieve first image. More...
struct image *	alloc_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	register_image (struct image *image)
	Register executable image. More...
void	unregister_image (struct image *image)
	Unregister executable image. More...
struct image *	find_image (const char *name)
	Find image by name. 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...
struct image *	image_find_selected (void)
	Find selected image. More...
int	image_set_trust (int require_trusted, int permanent)
	Change image trust requirement. 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...
static struct image *	image_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...

Variables
struct image	__attribute__
struct list_head	images
	List of registered images. More...
struct image *	current_image
	Currently-executing image. More...

Detailed Description

Executable images.

Definition in file image.h.

Macro Definition Documentation

IMAGE_REGISTERED

#define IMAGE_REGISTERED   0x00001

Image is registered.

Definition at line 64 of file image.h.

IMAGE_SELECTED

#define IMAGE_SELECTED   0x0002

Image is selected for execution.

Definition at line 67 of file image.h.

IMAGE_TRUSTED

#define IMAGE_TRUSTED   0x0004

Image is trusted.

Definition at line 70 of file image.h.

IMAGE_AUTO_UNREGISTER

#define IMAGE_AUTO_UNREGISTER   0x0008

Image will be automatically unregistered after execution.

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

PROBE_NORMAL

#define PROBE_NORMAL   02

Normal image probe priority.

Definition at line 129 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 137 of file image.h.

IMAGE_TYPES

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

Executable image type table.

Definition at line 140 of file image.h.

__image_type

#define __image_type

(

probe_order

)

__table_entry ( IMAGE_TYPES, probe_order )

An executable image type.

Definition at line 143 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 149 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 153 of file image.h.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER_OR_UBDL

)

have_images()

static int have_images ( void  )

inlinestatic

Test for existence of images.

Return values

existence

Some images exist

Definition at line 161 of file image.h.

                                       {
        return ( ! list_empty ( &images ) );
}

References images, and list_empty.

first_image()

static struct image* first_image ( void  )

inlinestatic

Retrieve first image.

Return values

image

Image, or NULL

Definition at line 170 of file image.h.

                                                  {
        return list_first_entry ( &images, struct image, list );
}

References images, image::list, and list_first_entry.

Referenced by ipxe().

alloc_image()

struct image* alloc_image

(

struct uri *

uri

)

Allocate executable image.

Parameters

uri	URI, or NULL

Return values

image

Executable image

Definition at line 90 of file image.c.

                                               {
        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;
}

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

Referenced by imgdownload(), and initrd_init().

image_set_uri()

int image_set_uri	(	struct image *	image,
		struct uri *	uri
	)

Set image URI.

Parameters

image	Image
uri	New image URI

Return values

rc	Return status code

Definition at line 119 of file image.c.

                                                           {
        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;
}

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

image	Image
name	New image name

Return values

rc	Return status code

Definition at line 144 of file image.c.

                                                             {
        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;
}

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

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

image_set_cmdline()

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

Set image command line.

Parameters

image	Image
cmdline	New image command line, or NULL

Return values

rc	Return status code

Definition at line 166 of file image.c.

                                                                   {

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

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

Referenced by image_clear_cmdline(), and imgsingle_exec().

register_image()

int register_image

(

struct image *

image

)

Register executable image.

Parameters

image

Executable image

Return values

rc	Return status code

Definition at line 210 of file image.c.

                                           {
        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;
}

References image::data, DBGC, image::flags, image_find_selected(), image_get(), image_probe(), IMAGE_REGISTERED, IMAGE_SELECTED, 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(), embedded_init(), imgdownload(), initrd_init(), pixbuf_okx(), script_exec(), and test_init().

unregister_image()

void unregister_image

(

struct image *

image

)

Unregister executable image.

Parameters

image

Executable image

Definition at line 252 of file image.c.

                                              {

        /* 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 );
}

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

find_image()

struct image* find_image

(

const char *

name

)

Find image by name.

Parameters

name	Image name

Return values

image

Executable image, or NULL

Definition at line 270 of file image.c.

                                               {
        struct image *image;

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

        return NULL;
}

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

Referenced by imgacquire(), and imgmulti_exec().

image_exec()

int image_exec

(

struct image *

image

)

Execute image.

Parameters

image

Executable image

Return values

rc	Return 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.

                                       {
        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;
}

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

image_replace()

int image_replace

(

struct image *

replacement

)

Set replacement image.

Parameters

replacement

Replacement image

Return values

rc	Return 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.

                                                {
        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;
}

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

image_select()

int image_select

(

struct image *

image

)

Select image for execution.

Parameters

image

Executable image

Return values

rc	Return status code

Definition at line 429 of file image.c.

                                         {
        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;
}

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

Referenced by embedded_init(), and imgselect().

image_find_selected()

struct image* image_find_selected

(

void

)

Find selected image.

Return values

image

Executable image, or NULL

Definition at line 451 of file image.c.

                                            {
        struct image *image;

        for_each_image ( image ) {
                if ( image->flags & IMAGE_SELECTED )
                        return image;
        }
        return NULL;
}

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

Referenced by imgsingle_exec(), and register_image().

image_set_trust()

int image_set_trust	(	int	require_trusted,
		int	permanent
	)

Change image trust requirement.

Parameters

require_trusted	Require trusted images
permanent	Make trust requirement permanent

Return values

rc	Return status code

Definition at line 468 of file image.c.

                                                           {

        /* 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;
}

References EACCES_PERMANENT, require_trusted_images, and require_trusted_images_permanent.

Referenced by imgtrust_exec().

image_pixbuf()

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

Create pixel buffer from image.

Parameters

image	Image
pixbuf	Pixel buffer to fill in

Return values

rc	Return status code

Definition at line 97 of file pixbuf.c.

                                                                       {
        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;
}

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

image	Image
offset	Offset within image
cursor	ASN.1 cursor to fill in

Return values

next	Offset 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.

                                               {
        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;
}

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

static struct image* image_get ( struct image *  image )

inlinestatic

Increment reference count on an image.

Parameters

image

Image

Return values

image

Image

Definition at line 196 of file image.h.

                                                               {
        ref_get ( &image->refcnt );
        return image;
}

References ref_get, and image::refcnt.

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

image_put()

static void image_put ( struct image *  image )

inlinestatic

Decrement reference count on an image.

Parameters

image

Image

Definition at line 206 of file image.h.

                                                     {
        ref_put ( &image->refcnt );
}

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

image_clear_cmdline()

static void image_clear_cmdline ( struct image *  image )

inlinestatic

Clear image command line.

Parameters

image

Image

Definition at line 215 of file image.h.

                                                               {
        image_set_cmdline ( image, NULL );
}

References image_set_cmdline(), and NULL.

image_trust()

static void image_trust ( struct image *  image )

inlinestatic

Set image as trusted.

Parameters

image

Image

Definition at line 224 of file image.h.

                                                       {
        image->flags |= IMAGE_TRUSTED;
}

References image::flags, and IMAGE_TRUSTED.

Referenced by imgverify().

image_untrust()

static void image_untrust ( struct image *  image )

inlinestatic

Set image as untrusted.

Parameters

image

Image

Definition at line 233 of file image.h.

                                                         {
        image->flags &= ~IMAGE_TRUSTED;
}

References image::flags, and IMAGE_TRUSTED.

Referenced by imgverify().

Variable Documentation

__attribute__

struct image __attribute__

images

struct list_head images

List of registered images.

Definition at line 56 of file image.c.

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

current_image

struct image* current_image

Currently-executing image.

Definition at line 59 of file image.c.

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