iPXE
Data Structures | Functions | Variables
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)
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 ( GPL2_OR_LATER  )
static void efi_download_close ( struct efi_download_file file,
int  rc 
) [static]

Transfer finished or was aborted.

Parameters:
fileData transfer file
rcReason for close

Definition at line 62 of file efi_download.c.

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

Referenced by efi_download_abort().

                                                                          {

        file->finish_callback ( file->context, EFIRC ( rc ) );

        intf_shutdown ( &file->xfer, rc );

        efi_snp_release();
}
static int efi_download_deliver_iob ( struct efi_download_file file,
struct io_buffer iobuf,
struct xfer_metadata meta 
) [static]

Process received data.

Parameters:
fileData transfer file
iobufI/O buffer
metaData transfer metadata
Return values:
rcReturn status code

Definition at line 79 of file efi_download.c.

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

                                                                   {
        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;
}
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 
) [static]

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

Parameters:
ThisiPXE Download Protocol instance
UrlURL to download from
DataCallbackCallback that will be invoked when data arrives
FinishCallbackCallback that will be invoked when the download ends
ContextContext passed to the Data and Finish callbacks
FileToken that can be used to abort the download
Return values:
StatusEFI status code

Definition at line 132 of file efi_download.c.

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

                                                {
        struct efi_download_file *file;
        int rc;

        file = malloc ( sizeof ( struct efi_download_file ) );
        if ( file == NULL ) {
                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 );
                return EFIRC ( rc );
        }

        efi_snp_claim();
        file->pos = 0;
        file->data_callback = DataCallback;
        file->finish_callback = FinishCallback;
        file->context = Context;
        *File = file;
        return EFI_SUCCESS;
}
static 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:
ThisiPXE Download Protocol instance
FileToken obtained from Start
StatusReason for aborting the download
Return values:
StatusEFI status code

Definition at line 173 of file efi_download.c.

References EEFI, efi_download_close(), and EFI_SUCCESS.

                                         {
        struct efi_download_file *file = File;

        efi_download_close ( file, -EEFI ( Status ) );
        return EFI_SUCCESS;
}
static 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:
ThisiPXE Download Protocol instance
Return values:
StatusEFI status code

Definition at line 190 of file efi_download.c.

References EFI_SUCCESS, and step().

                                                            {
        step();
        return EFI_SUCCESS;
}

Install iPXE download protocol.

Parameters:
handleEFI handle
Return values:
rcReturn status code

Definition at line 208 of file efi_download.c.

References EFI_SYSTEM_TABLE::BootServices, DBG, EEFI, efi_systab, EFI_BOOT_SERVICES::InstallMultipleProtocolInterfaces, ipxe_download_protocol_guid, NULL, rc, and strerror().

Referenced by efi_image_exec().

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

Variable Documentation

iPXE download protocol GUID

Definition at line 34 of file efi_download.c.

Referenced by efi_download_install(), and efi_download_uninstall().

Initial value:

Data transfer interface operations.

Definition at line 110 of file efi_download.c.

Initial value:

EFI download data transfer interface descriptor.

Definition at line 116 of file efi_download.c.

Initial value:
 {
        .Start = efi_download_start,
        .Abort = efi_download_abort,
        .Poll = efi_download_poll
}

Publicly exposed iPXE download protocol.

Definition at line 196 of file efi_download.c.