Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Try to port over Geoff Lywood's gPXE Download Protocol for EFI to iPXE.
Three points of reference:
	-Geoff's monolithic patch to indicate the current state of his effort
	-Geoff's 'RFC' posting to gpxe-devel in 2010 to help identify relevant parts of the monolithic patch
	-Changes to posix_io.c that resemble the changes needed for 'old' gPXE calls to work in iPXE world
It builds and runs without errors, but haven't made changes to elilo required to really test it yet
  • Loading branch information
Jarrod Johnson authored and Jarrod Johnson committed Aug 8, 2011
1 parent 3d89959 commit d748ebf
Show file tree
Hide file tree
Showing 2 changed files with 384 additions and 0 deletions.
154 changes: 154 additions & 0 deletions src/include/ipxe/efi/ipxe_download.h
@@ -0,0 +1,154 @@
/*
* Copyright (C) 2010 VMware, Inc. All Rights Reserved.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of the
* License, or any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*/

#ifndef IPXE_DOWNLOAD_H
#define IPXE_DOWNLOAD_H

FILE_LICENCE ( GPL2_OR_LATER );

/** @file
*
* gPXE Download Protocol
*
* EFI applications started by gPXE may use this interface to download files.
*/

typedef struct _IPXE_DOWNLOAD_PROTOCOL IPXE_DOWNLOAD_PROTOCOL;

/** Token to represent a currently downloading file */
typedef VOID *IPXE_DOWNLOAD_FILE;

/**
* Callback function that is invoked when data arrives for a particular file.
*
* Not all protocols will deliver data in order. Clients should not rely on the
* order of data delivery matching the order in the file.
*
* Some protocols are capable of determining the file size near the beginning
* of data transfer. To allow the client to allocate memory more efficiently,
* gPXE may give a hint about the file size by calling the Data callback with
* a zero BufferLength and the file size in FileOffset. Clients should be
* prepared to deal with more or less data than the hint actually arriving.
*
* @v Context Context provided to the Start function
* @v Buffer New data
* @v BufferLength Length of new data in bytes
* @v FileOffset Offset of new data in the file
* @ret Status EFI_SUCCESS to continue the download,
* or any error code to abort.
*/
typedef
EFI_STATUS
(EFIAPI *IPXE_DOWNLOAD_DATA_CALLBACK)(
IN VOID *Context,
IN VOID *Buffer,
IN UINTN BufferLength,
IN UINTN FileOffset
);

/**
* Callback function that is invoked when the file is finished downloading, or
* when a connection unexpectedly closes or times out.
*
* The finish callback is also called when a download is aborted by the Abort
* function (below).
*
* @v Context Context provided to the Start function
* @v Status Reason for termination: EFI_SUCCESS when the entire
* file was transferred successfully, or an error
* otherwise
*/
typedef
void
(EFIAPI *IPXE_DOWNLOAD_FINISH_CALLBACK)(
IN VOID *Context,
IN EFI_STATUS Status
);

/**
* Start downloading a file, and register callback functions to handle the
* download.
*
* @v This gPXE Download Protocol instance
* @v Url URL to download from
* @v DataCallback Callback that will be invoked when data arrives
* @v FinishCallback Callback that will be invoked when the download ends
* @v Context Context passed to the Data and Finish callbacks
* @v File Token that can be used to abort the download
* @ret Status EFI status code
*/
typedef
EFI_STATUS
(EFIAPI *IPXE_DOWNLOAD_START)(
IN IPXE_DOWNLOAD_PROTOCOL *This,
IN CHAR8 *Url,
IN IPXE_DOWNLOAD_DATA_CALLBACK DataCallback,
IN IPXE_DOWNLOAD_FINISH_CALLBACK FinishCallback,
IN VOID *Context,
OUT IPXE_DOWNLOAD_FILE *File
);

/**
* Forcibly abort downloading a file that is currently in progress.
*
* It is not safe to call this function after the Finish callback has executed.
*
* @v This gPXE Download Protocol instance
* @v File Token obtained from Start
* @v Status Reason for aborting the download
* @ret Status EFI status code
*/
typedef
EFI_STATUS
(EFIAPI *IPXE_DOWNLOAD_ABORT)(
IN IPXE_DOWNLOAD_PROTOCOL *This,
IN IPXE_DOWNLOAD_FILE File,
IN EFI_STATUS Status
);

/**
* Poll for more data from gPXE. This function will invoke the registered
* callbacks if data is available or if downloads complete.
*
* @v This gPXE Download Protocol instance
* @ret Status EFI status code
*/
typedef
EFI_STATUS
(EFIAPI *IPXE_DOWNLOAD_POLL)(
IN IPXE_DOWNLOAD_PROTOCOL *This
);

/**
* The gPXE Download Protocol.
*
* gPXE will attach a gPXE Download Protocol to the DeviceHandle in the Loaded
* Image Protocol of all child EFI applications.
*/
struct _IPXE_DOWNLOAD_PROTOCOL {
IPXE_DOWNLOAD_START Start;
IPXE_DOWNLOAD_ABORT Abort;
IPXE_DOWNLOAD_POLL Poll;
};

#define IPXE_DOWNLOAD_PROTOCOL_GUID \
{ \
0x3eaeaebd, 0xdecf, 0x493b, { 0x9b, 0xd1, 0xcd, 0xb2, 0xde, 0xca, 0xe7, 0x19 } \
}

#endif
230 changes: 230 additions & 0 deletions src/interface/efi/efi_download.c
@@ -0,0 +1,230 @@
/*
* Copyright (C) 2010 VMware, Inc. All Rights Reserved.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of the
* License, or any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*/

FILE_LICENCE ( GPL2_OR_LATER );

#include <stdlib.h>
#include <string.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/ipxe_download.h>

/** gPXE download protocol GUID */
static EFI_GUID ipxe_download_protocol_guid
= IPXE_DOWNLOAD_PROTOCOL_GUID;

/** A single in-progress file */
struct efi_download_file {
/** Data transfer interface that provides downloaded data */
struct interface xfer;

/** Current file position */
size_t pos;

/** Data callback */
IPXE_DOWNLOAD_DATA_CALLBACK data_callback;

/** Finish callback */
IPXE_DOWNLOAD_FINISH_CALLBACK finish_callback;

/** Callback context */
void *context;
};

/* xfer interface */

/**
* Transfer finished or was aborted
*
* @v file Data transfer file
* @v rc Reason for close
*/
static void efi_download_close ( struct efi_download_file *file, int rc ) {

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

intf_shutdown ( &file->xfer, rc );
}

/**
* Process received data
*
* @v file Data transfer file
* @v iobuf I/O buffer
* @v meta Data transfer metadata
* @ret rc Return status code
*/
static int efi_download_deliver_iob ( struct efi_download_file *file,
struct io_buffer *iobuf,
struct xfer_metadata *meta ) {
EFI_STATUS efirc;
size_t len = iob_len ( iobuf );

/* Calculate new buffer position */
if ( meta->flags & XFER_FL_ABS_OFFSET )
file->pos = 0;
file->pos += meta->offset;

/* Call out to the data handler */
efirc = file->data_callback ( file->context, iobuf->data,
len, file->pos );

/* Update current buffer position */
file->pos += len;

free_iob ( iobuf );
return EFIRC_TO_RC ( efirc );
}

/** Data transfer interface operations */
static struct interface_operation efi_xfer_operations[] = {
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 data transfer interface descriptor */
static struct interface_descriptor efi_download_file_xfer_desc =
INTF_DESC ( struct efi_download_file, xfer, efi_xfer_operations );

/**
* Start downloading a file, and register callback functions to handle the
* download.
*
* @v This gPXE Download Protocol instance
* @v Url URL to download from
* @v DataCallback Callback that will be invoked when data arrives
* @v FinishCallback Callback that will be invoked when the download ends
* @v Context Context passed to the Data and Finish callbacks
* @v File Token that can be used to abort the download
* @ret Status EFI status code
*/
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 ) {
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 RC_TO_EFIRC ( rc );
}

file->pos = 0;
file->data_callback = DataCallback;
file->finish_callback = FinishCallback;
file->context = Context;
*File = file;
return EFI_SUCCESS;
}

/**
* Forcibly abort downloading a file that is currently in progress.
*
* It is not safe to call this function after the Finish callback has executed.
*
* @v This gPXE Download Protocol instance
* @v File Token obtained from Start
* @v Status Reason for aborting the download
* @ret Status EFI status code
*/
static EFI_STATUS EFIAPI
efi_download_abort ( IPXE_DOWNLOAD_PROTOCOL *This __unused,
IPXE_DOWNLOAD_FILE File,
EFI_STATUS Status ) {
struct efi_download_file *file = File;

efi_download_close ( file, EFIRC_TO_RC ( Status ) );
return EFI_SUCCESS;
}

/**
* Poll for more data from gPXE. This function will invoke the registered
* callbacks if data is available or if downloads complete.
*
* @v This gPXE Download Protocol instance
* @ret Status EFI status code
*/
static EFI_STATUS EFIAPI
efi_download_poll ( IPXE_DOWNLOAD_PROTOCOL *This __unused ) {
step();
return EFI_SUCCESS;
}

/** Publicly exposed gPXE download protocol */
static IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface = {
.Start = efi_download_start,
.Abort = efi_download_abort,
.Poll = efi_download_poll
};

/**
* Create a new device handle with a gPXE download protocol attached to it.
*
* @v device_handle Newly created device handle (output)
* @ret rc Return status code
*/
int efi_download_install ( EFI_HANDLE *device_handle ) {
EFI_BOOT_SERVICES *bs = efi_systab->BootServices;
EFI_STATUS efirc;
EFI_HANDLE handle = NULL;

DBG ( "Installing ipxe protocol interface (%p)... ",
&ipxe_download_protocol_interface );
efirc = bs->InstallMultipleProtocolInterfaces (
&handle,
&ipxe_download_protocol_guid,
&ipxe_download_protocol_interface,
NULL );
if ( efirc ) {
DBG ( "failed (%s)\n", efi_strerror ( efirc ) );
return EFIRC_TO_RC ( efirc );
}

DBG ( "success (%p)\n", handle );
*device_handle = handle;
return 0;
}

/**
* Remove the gPXE download protocol from the given handle, and if nothing
* else is attached, destroy the handle.
*
* @v device_handle EFI device handle to remove from
*/
void efi_download_uninstall ( EFI_HANDLE device_handle ) {
EFI_BOOT_SERVICES *bs = efi_systab->BootServices;

bs->UninstallMultipleProtocolInterfaces (
device_handle,
ipxe_download_protocol_guid,
ipxe_download_protocol_interface );
}

0 comments on commit d748ebf

Please sign in to comment.