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. More...
 
static int efi_download_deliver_iob (struct efi_download_file *file, struct io_buffer *iobuf, struct xfer_metadata *meta)
 Process received data. More...
 
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. More...
 
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. More...
 
static EFI_STATUS EFIAPI efi_download_poll (IPXE_DOWNLOAD_PROTOCOL *This __unused)
 Poll for more data from iPXE. More...
 
int efi_download_install (EFI_HANDLE handle)
 Install iPXE download protocol. More...
 
void efi_download_uninstall (EFI_HANDLE handle)
 Uninstall iPXE download protocol. More...
 

Variables

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

Function Documentation

◆ FILE_LICENCE()

FILE_LICENCE ( GPL2_OR_LATER  )

◆ efi_download_close()

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.

62  {
63 
64  file->finish_callback ( file->context, EFIRC ( rc ) );
65 
66  intf_shutdown ( &file->xfer, rc );
67 
69 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
void intf_shutdown(struct interface *intf, int rc)
Shut down an object interface.
Definition: interface.c:273
void * context
Callback context.
Definition: efi_download.c:51
IPXE_DOWNLOAD_FINISH_CALLBACK finish_callback
Finish callback.
Definition: efi_download.c:48
static void efi_snp_release(void)
Release network devices for use via SNP.
Definition: efi_snp.h:96
struct interface xfer
Data transfer interface that provides downloaded data.
Definition: efi_download.c:39
#define EFIRC(rc)
Convert an iPXE status code to an EFI status code.
Definition: efi.h:149

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

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.

81  {
82  EFI_STATUS efirc;
83  size_t len = iob_len ( iobuf );
84  int rc;
85 
86  /* Calculate new buffer position */
87  if ( meta->flags & XFER_FL_ABS_OFFSET )
88  file->pos = 0;
89  file->pos += meta->offset;
90 
91  /* Call out to the data handler */
92  if ( ( efirc = file->data_callback ( file->context, iobuf->data,
93  len, file->pos ) ) != 0 ) {
94  rc = -EEFI ( efirc );
95  goto err_callback;
96  }
97 
98  /* Update current buffer position */
99  file->pos += len;
100 
101  /* Success */
102  rc = 0;
103 
104  err_callback:
105  free_iob ( iobuf );
106  return rc;
107 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
#define EEFI(efirc)
Convert an EFI status code to an iPXE status code.
Definition: efi.h:157
IPXE_DOWNLOAD_DATA_CALLBACK data_callback
Data callback.
Definition: efi_download.c:45
#define XFER_FL_ABS_OFFSET
Offset is absolute.
Definition: xfer.h:47
void free_iob(struct io_buffer *iobuf)
Free I/O buffer.
Definition: iobuf.c:145
void * context
Callback context.
Definition: efi_download.c:51
int meta(WINDOW *, bool)
static size_t iob_len(struct io_buffer *iobuf)
Calculate length of data in an I/O buffer.
Definition: iobuf.h:151
size_t pos
Current file position.
Definition: efi_download.c:42
uint32_t len
Length.
Definition: ena.h:14
void * data
Start of data.
Definition: iobuf.h:44
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35

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

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.

137  {
138  struct efi_download_file *file;
139  int rc;
140 
141  file = malloc ( sizeof ( struct efi_download_file ) );
142  if ( file == NULL ) {
143  return EFI_OUT_OF_RESOURCES;
144  }
145 
147  rc = xfer_open ( &file->xfer, LOCATION_URI_STRING, Url );
148  if ( rc ) {
149  free ( file );
150  return EFIRC ( rc );
151  }
152 
153  efi_snp_claim();
154  file->pos = 0;
155  file->data_callback = DataCallback;
156  file->finish_callback = FinishCallback;
157  file->context = Context;
158  *File = file;
159  return EFI_SUCCESS;
160 }
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
IPXE_DOWNLOAD_DATA_CALLBACK data_callback
Data callback.
Definition: efi_download.c:45
void * context
Callback context.
Definition: efi_download.c:51
static void efi_snp_claim(void)
Claim network devices for use by iPXE.
Definition: efi_snp.h:88
A single in-progress file.
Definition: efi_download.c:37
IPXE_DOWNLOAD_FINISH_CALLBACK finish_callback
Finish callback.
Definition: efi_download.c:48
#define EFI_OUT_OF_RESOURCES
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:129
static void(* free)(struct refcnt *refcnt))
Definition: refcnt.h:54
static struct interface_descriptor efi_download_file_xfer_desc
EFI download data transfer interface descriptor.
Definition: efi_download.c:116
int xfer_open(struct interface *intf, int type,...)
Open location.
Definition: open.c:203
void * malloc(size_t size)
Allocate memory.
Definition: malloc.c:583
size_t pos
Current file position.
Definition: efi_download.c:42
#define EFI_SUCCESS
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:120
struct interface xfer
Data transfer interface that provides downloaded data.
Definition: efi_download.c:39
Location is a URI string.
Definition: open.h:34
static void intf_init(struct interface *intf, struct interface_descriptor *desc, struct refcnt *refcnt)
Initialise an object interface.
Definition: interface.h:173
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
#define EFIRC(rc)
Convert an iPXE status code to an EFI status code.
Definition: efi.h:149

References efi_download_file::context, efi_download_file::data_callback, efi_download_file_xfer_desc, 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().

◆ efi_download_abort()

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.

175  {
176  struct efi_download_file *file = File;
177 
178  efi_download_close ( file, -EEFI ( Status ) );
179  return EFI_SUCCESS;
180 }
#define EEFI(efirc)
Convert an EFI status code to an iPXE status code.
Definition: efi.h:157
PXENV_STATUS_t Status
PXE status code.
Definition: pxe_api.h:57
A single in-progress file.
Definition: efi_download.c:37
#define EFI_SUCCESS
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:120
static void efi_download_close(struct efi_download_file *file, int rc)
Transfer finished or was aborted.
Definition: efi_download.c:62

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

◆ efi_download_poll()

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.

190  {
191  step();
192  return EFI_SUCCESS;
193 }
#define EFI_SUCCESS
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:120
void step(void)
Single-step a single process.
Definition: process.c:98

References EFI_SUCCESS, and step().

◆ efi_download_install()

int efi_download_install ( EFI_HANDLE  handle)

Install iPXE download protocol.

Parameters
handleEFI handle
Return values
rcReturn status code

Definition at line 208 of file efi_download.c.

208  {
210  EFI_STATUS efirc;
211  int rc;
212 
214  &handle,
217  NULL );
218  if ( efirc ) {
219  rc = -EEFI ( efirc );
220  DBG ( "Could not install download protocol: %s\n",
221  strerror ( rc ) );
222  return rc;
223  }
224 
225  return 0;
226 }
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2000
struct arbelprm_rc_send_wqe rc
Definition: arbel.h:14
#define EEFI(efirc)
Convert an EFI status code to an iPXE status code.
Definition: efi.h:157
EFI_INSTALL_MULTIPLE_PROTOCOL_INTERFACES InstallMultipleProtocolInterfaces
Definition: UefiSpec.h:1915
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
EFI Boot Services Table.
Definition: UefiSpec.h:1836
static IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface
Publicly exposed iPXE download protocol.
Definition: efi_download.c:196
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:35
EFI_SYSTEM_TABLE * efi_systab
#define DBG(...)
Print a debugging message.
Definition: compiler.h:498
uint16_t handle
Handle.
Definition: smbios.h:16
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
static EFI_GUID ipxe_download_protocol_guid
iPXE download protocol GUID
Definition: efi_download.c:34

References EFI_SYSTEM_TABLE::BootServices, DBG, EEFI, 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
handleEFI handle

Definition at line 233 of file efi_download.c.

233  {
235 
237  handle,
240 }
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2000
EFI Boot Services Table.
Definition: UefiSpec.h:1836
EFI_UNINSTALL_MULTIPLE_PROTOCOL_INTERFACES UninstallMultipleProtocolInterfaces
Definition: UefiSpec.h:1916
static IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface
Publicly exposed iPXE download protocol.
Definition: efi_download.c:196
EFI_SYSTEM_TABLE * efi_systab
uint16_t handle
Handle.
Definition: smbios.h:16
#define NULL
NULL pointer (VOID *)
Definition: Base.h:362
static EFI_GUID ipxe_download_protocol_guid
iPXE download protocol GUID
Definition: efi_download.c:34

References EFI_SYSTEM_TABLE::BootServices, 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:
= {
}
void intf_close(struct interface *intf, int rc)
Close an object interface.
Definition: interface.c:244
static int efi_download_deliver_iob(struct efi_download_file *file, struct io_buffer *iobuf, struct xfer_metadata *meta)
Process received data.
Definition: efi_download.c:79
A single in-progress file.
Definition: efi_download.c:37
#define INTF_OP(op_type, object_type, op_func)
Define an object interface operation.
Definition: interface.h:32
int xfer_deliver(struct interface *intf, struct io_buffer *iobuf, struct xfer_metadata *meta)
Deliver datagram.
Definition: xfer.c:193
static void efi_download_close(struct efi_download_file *file, int rc)
Transfer finished or was aborted.
Definition: efi_download.c:62

Data transfer interface operations.

Definition at line 110 of file efi_download.c.

◆ efi_download_file_xfer_desc

struct interface_descriptor efi_download_file_xfer_desc
static
Initial value:
=
static struct interface_operation efi_xfer_operations[]
Data transfer interface operations.
Definition: efi_download.c:110
A single in-progress file.
Definition: efi_download.c:37
#define INTF_DESC(object_type, intf, operations)
Define an object interface descriptor.
Definition: interface.h:65
struct interface xfer
Data transfer interface that provides downloaded data.
Definition: efi_download.c:39

EFI download data transfer interface descriptor.

Definition at line 116 of file efi_download.c.

Referenced by efi_download_start().

◆ ipxe_download_protocol_interface

IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface
static
Initial value:
= {
}
static EFI_STATUS EFIAPI efi_download_poll(IPXE_DOWNLOAD_PROTOCOL *This __unused)
Poll for more data from iPXE.
Definition: efi_download.c:190
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.
Definition: efi_download.c:132
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.
Definition: efi_download.c:173

Publicly exposed iPXE download protocol.

Definition at line 196 of file efi_download.c.

Referenced by efi_download_install(), and efi_download_uninstall().