[efi] Add iPXE download protocol

iPXE exposes some extended capabilities via the PXE FILE API to allow
NBPs such as pxelinux to use protocols other than TFTP.  Provide an
equivalent interface as a UEFI protocol so that EFI binaries may also
take advantage of iPXE's extended capabilities.

This can be used with a patched version of elilo, for example:

  http://comments.gmane.org/gmane.comp.boot-loaders.elilo.general/147

Signed-off-by: Michael Brown <mcb30@ipxe.org>

2 files changed, 156 insertions, 0 deletions

diff --git a/src/include/ipxe/efi/efi.h b/src/include/ipxe/efi/efi.h
index 8a216b5..b5ce7df 100644
--- a/src/include/ipxe/efi/efi.h
+++ b/src/include/ipxe/efi/efi.h
@@ -142,5 +142,7 @@ extern EFI_SYSTEM_TABLE *efi_systab;
 extern const char * efi_strerror ( EFI_STATUS efirc );
 extern EFI_STATUS efi_init ( EFI_HANDLE image_handle,
 			     EFI_SYSTEM_TABLE *systab );
+extern int efi_download_install ( EFI_HANDLE *device_handle );
+extern void efi_download_uninstall ( EFI_HANDLE device_handle );
 
 #endif /* _IPXE_EFI_H */
diff --git a/src/include/ipxe/efi/ipxe_download.h b/src/include/ipxe/efi/ipxe_download.h
new file mode 100644
index 0000000..282d1ee
--- /dev/null
+++ b/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
+ *
+ * iPXE Download Protocol
+ *
+ * EFI applications started by iPXE 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,
+ * iPXE 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		iPXE 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		iPXE 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 iPXE. This function will invoke the registered
+ * callbacks if data is available or if downloads complete.
+ *
+ * @v This		iPXE Download Protocol instance
+ * @ret Status		EFI status code
+ */
+typedef
+EFI_STATUS
+(EFIAPI *IPXE_DOWNLOAD_POLL)(
+  IN IPXE_DOWNLOAD_PROTOCOL *This
+  );
+
+/**
+ * The iPXE Download Protocol.
+ *
+ * iPXE will attach a iPXE 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