efi_download.c File Reference

#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <ipxe/open.h>
#include <ipxe/process.h>
#include <ipxe/iobuf.h>
#include <ipxe/xfer.h>
#include <ipxe/efi/efi.h>
#include <ipxe/efi/efi_snp.h>
#include <ipxe/efi/efi_download.h>

Go to the source code of this file.

Data Structures
struct	efi_download_file
	A single in-progress file. More...

Functions
	FILE_LICENCE (GPL2_OR_LATER)
	FILE_SECBOOT (PERMITTED)
static void	efi_download_close (struct efi_download_file *file, int rc)
	Transfer finished or was aborted.
static int	efi_download_deliver_iob (struct efi_download_file *file, struct io_buffer *iobuf, struct xfer_metadata *meta)
	Process received data.
static EFI_STATUS EFIAPI	efi_download_start (IPXE_DOWNLOAD_PROTOCOL *This __unused, CHAR8 *Url, IPXE_DOWNLOAD_DATA_CALLBACK DataCallback, IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback, VOID *Context, IPXE_DOWNLOAD_FILE *File)
	Start downloading a file, and register callback functions to handle the download.
static EFI_STATUS EFIAPI	efi_download_abort (IPXE_DOWNLOAD_PROTOCOL *This __unused, IPXE_DOWNLOAD_FILE File, EFI_STATUS Status)
	Forcibly abort downloading a file that is currently in progress.
static EFI_STATUS EFIAPI	efi_download_poll (IPXE_DOWNLOAD_PROTOCOL *This __unused)
	Poll for more data from iPXE.
int	efi_download_install (EFI_HANDLE handle)
	Install iPXE download protocol.
void	efi_download_uninstall (EFI_HANDLE handle)
	Uninstall iPXE download protocol.

Variables
static EFI_GUID	ipxe_download_protocol_guid = IPXE_DOWNLOAD_PROTOCOL_GUID
	iPXE download protocol GUID
static struct interface_operation	efi_xfer_operations []
	Data transfer interface operations.
static struct interface_descriptor	efi_download_file_xfer_desc
	EFI download data transfer interface descriptor.
static IPXE_DOWNLOAD_PROTOCOL	ipxe_download_protocol_interface
	Publicly exposed iPXE download protocol.

Function Documentation

FILE_LICENCE()

FILE_LICENCE

(

GPL2_OR_LATER

)

FILE_SECBOOT()

FILE_SECBOOT

(

PERMITTED

)

efi_download_close()

void efi_download_close ( struct efi_download_file * file, int rc )

static

Transfer finished or was aborted.

Parameters

file	Data transfer file
rc	Reason for close

Definition at line 63 of file efi_download.c.

                                                                          {
 
        file->finish_callback ( file->context, EFIRC ( rc ) );
 
        intf_shutdown ( &file->xfer, rc );
 
        efi_snp_release();
}

References efi_download_file::context, efi_snp_release(), EFIRC, efi_download_file::finish_callback, intf_shutdown(), rc, and efi_download_file::xfer.

Referenced by efi_download_abort().

efi_download_deliver_iob()

int efi_download_deliver_iob ( struct efi_download_file * file, struct io_buffer * iobuf, struct xfer_metadata * meta )

static

Process received data.

Parameters

file	Data transfer file
iobuf	I/O buffer
meta	Data transfer metadata

Return values

rc	Return status code

Definition at line 80 of file efi_download.c.

                                                                   {
        EFI_STATUS efirc;
        size_t len = iob_len ( iobuf );
        int rc;
 
        /* Calculate new buffer position */
        if ( meta->flags & XFER_FL_ABS_OFFSET )
                file->pos = 0;
        file->pos += meta->offset;
 
        /* Call out to the data handler */
        if ( ( efirc = file->data_callback ( file->context, iobuf->data,
                                             len, file->pos ) ) != 0 ) {
                rc = -EEFI ( efirc );
                goto err_callback;
        }
 
        /* Update current buffer position */
        file->pos += len;
 
        /* Success */
        rc = 0;
 
 err_callback:
        free_iob ( iobuf );
        return rc;
}

References efi_download_file::context, io_buffer::data, efi_download_file::data_callback, EEFI, free_iob(), iob_len(), len, meta, efi_download_file::pos, rc, and XFER_FL_ABS_OFFSET.

efi_download_start()

EFI_STATUS EFIAPI efi_download_start ( IPXE_DOWNLOAD_PROTOCOL *This __unused, CHAR8 * Url, IPXE_DOWNLOAD_DATA_CALLBACK DataCallback, IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback, VOID * Context, IPXE_DOWNLOAD_FILE * File )

static

Start downloading a file, and register callback functions to handle the download.

Parameters

This	iPXE Download Protocol instance
Url	URL to download from
DataCallback	Callback that will be invoked when data arrives
FinishCallback	Callback that will be invoked when the download ends
Context	Context passed to the Data and Finish callbacks
File	Token that can be used to abort the download

Return values

Status

EFI status code

Definition at line 133 of file efi_download.c.

                                                {
        struct efi_download_file *file;
        int rc;
 
        efi_snp_claim();
 
        file = malloc ( sizeof ( struct efi_download_file ) );
        if ( file == NULL ) {
                efi_snp_release();
                return EFI_OUT_OF_RESOURCES;
        }
 
        intf_init ( &file->xfer, &efi_download_file_xfer_desc, NULL );
        rc = xfer_open ( &file->xfer, LOCATION_URI_STRING, Url );
        if ( rc ) {
                free ( file );
                efi_snp_release();
                return EFIRC ( rc );
        }
 
        file->pos = 0;
        file->data_callback = DataCallback;
        file->finish_callback = FinishCallback;
        file->context = Context;
        *File = file;
        return EFI_SUCCESS;
}

References __unused, efi_download_file::context, efi_download_file::data_callback, efi_download_file_xfer_desc, EFI_OUT_OF_RESOURCES, efi_snp_claim(), efi_snp_release(), EFI_SUCCESS, EFIRC, efi_download_file::finish_callback, free, intf_init(), LOCATION_URI_STRING, malloc(), NULL, efi_download_file::pos, rc, VOID, efi_download_file::xfer, and xfer_open().

efi_download_abort()

EFI_STATUS EFIAPI efi_download_abort ( IPXE_DOWNLOAD_PROTOCOL *This __unused, IPXE_DOWNLOAD_FILE File, EFI_STATUS Status )

static

Forcibly abort downloading a file that is currently in progress.

It is not safe to call this function after the Finish callback has executed.

Parameters

This	iPXE Download Protocol instance
File	Token obtained from Start
Status	Reason for aborting the download

Return values

Status

EFI status code

Definition at line 177 of file efi_download.c.

                                         {
        struct efi_download_file *file = File;
 
        efi_download_close ( file, -EEFI ( Status ) );
        return EFI_SUCCESS;
}

References __unused, EEFI, efi_download_close(), EFI_SUCCESS, and Status.

efi_download_poll()

EFI_STATUS EFIAPI efi_download_poll ( IPXE_DOWNLOAD_PROTOCOL *This __unused )

static

Poll for more data from iPXE.

This function will invoke the registered callbacks if data is available or if downloads complete.

Parameters

This	iPXE Download Protocol instance

Return values

Status

EFI status code

Definition at line 194 of file efi_download.c.

                                                            {
        step();
        return EFI_SUCCESS;
}

References __unused, EFI_SUCCESS, and step().

efi_download_install()

int efi_download_install

(

EFI_HANDLE

handle

)

Install iPXE download protocol.

Parameters

handle

EFI handle

Return values

rc	Return status code

Definition at line 212 of file efi_download.c.

                                               {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
        EFI_STATUS efirc;
        int rc;
 
        efirc = bs->InstallMultipleProtocolInterfaces (
                        &handle,
                        &ipxe_download_protocol_guid,
                        &ipxe_download_protocol_interface,
                        NULL );
        if ( efirc ) {
                rc = -EEFI ( efirc );
                DBG ( "Could not install download protocol: %s\n",
                      strerror ( rc ) );
                return rc;
        }
 
        return 0;
}

References DBG, EEFI, EFI_HANDLE, efi_systab, handle, EFI_BOOT_SERVICES::InstallMultipleProtocolInterfaces, ipxe_download_protocol_guid, ipxe_download_protocol_interface, NULL, rc, and strerror().

Referenced by efi_image_exec().

efi_download_uninstall()

void efi_download_uninstall

(

EFI_HANDLE

handle

)

Uninstall iPXE download protocol.

Parameters

handle

EFI handle

Definition at line 237 of file efi_download.c.

                                                  {
        EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
 
        bs->UninstallMultipleProtocolInterfaces (
                        handle,
                        &ipxe_download_protocol_guid,
                        &ipxe_download_protocol_interface, NULL );
}

References EFI_HANDLE, efi_systab, handle, ipxe_download_protocol_guid, ipxe_download_protocol_interface, NULL, and EFI_BOOT_SERVICES::UninstallMultipleProtocolInterfaces.

Referenced by efi_image_exec().

Variable Documentation

ipxe_download_protocol_guid

EFI_GUID ipxe_download_protocol_guid = IPXE_DOWNLOAD_PROTOCOL_GUID

static

iPXE download protocol GUID

Definition at line 34 of file efi_download.c.

Referenced by efi_download_install(), and efi_download_uninstall().

efi_xfer_operations

struct interface_operation efi_xfer_operations[]

static

Initial value:

= {
        INTF_OP ( xfer_deliver, struct efi_download_file *, efi_download_deliver_iob ),
        INTF_OP ( intf_close, struct efi_download_file *, efi_download_close ),
}

Data transfer interface operations.

Definition at line 111 of file efi_download.c.

                                                          {
        INTF_OP ( xfer_deliver, struct efi_download_file *, efi_download_deliver_iob ),
        INTF_OP ( intf_close, struct efi_download_file *, efi_download_close ),
};

efi_download_file_xfer_desc

struct interface_descriptor efi_download_file_xfer_desc

static

Initial value:

=
        INTF_DESC ( struct efi_download_file, xfer, efi_xfer_operations )

EFI download data transfer interface descriptor.

Definition at line 117 of file efi_download.c.

Referenced by efi_download_start().

ipxe_download_protocol_interface

IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface

static

Initial value:

= {
        .Start = efi_download_start,
        .Abort = efi_download_abort,
        .Poll = efi_download_poll
}

Publicly exposed iPXE download protocol.

Definition at line 200 of file efi_download.c.

                                                                 {
        .Start = efi_download_start,
        .Abort = efi_download_abort,
        .Poll = efi_download_poll
};

Referenced by efi_download_install(), and efi_download_uninstall().