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:278
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:99
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:163

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:171
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:146
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:155
size_t pos
Current file position.
Definition: efi_download.c:42
void * data
Start of data.
Definition: iobuf.h:48
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:31
uint32_t len
Length.
Definition: ena.h:14

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  efi_snp_claim();
142 
143  file = malloc ( sizeof ( struct efi_download_file ) );
144  if ( file == NULL ) {
145  efi_snp_release();
146  return EFI_OUT_OF_RESOURCES;
147  }
148 
150  rc = xfer_open ( &file->xfer, LOCATION_URI_STRING, Url );
151  if ( rc ) {
152  free ( file );
153  efi_snp_release();
154  return EFIRC ( rc );
155  }
156 
157  file->pos = 0;
158  file->data_callback = DataCallback;
159  file->finish_callback = FinishCallback;
160  file->context = Context;
161  *File = file;
162  return EFI_SUCCESS;
163 }
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:91
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:123
static void(* free)(struct refcnt *refcnt))
Definition: refcnt.h:54
static void efi_snp_release(void)
Release network devices for use via SNP.
Definition: efi_snp.h:99
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:202
void * malloc(size_t size)
Allocate memory.
Definition: malloc.c:583
Location is a URI string.
Definition: open.h:34
size_t pos
Current file position.
Definition: efi_download.c:42
#define EFI_SUCCESS
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:114
struct interface xfer
Data transfer interface that provides downloaded data.
Definition: efi_download.c:39
static void intf_init(struct interface *intf, struct interface_descriptor *desc, struct refcnt *refcnt)
Initialise an object interface.
Definition: interface.h:203
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
#define EFIRC(rc)
Convert an iPXE status code to an EFI status code.
Definition: efi.h:163

References 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, 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 176 of file efi_download.c.

178  {
179  struct efi_download_file *file = File;
180 
181  efi_download_close ( file, -EEFI ( Status ) );
182  return EFI_SUCCESS;
183 }
#define EEFI(efirc)
Convert an EFI status code to an iPXE status code.
Definition: efi.h:171
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:114
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 193 of file efi_download.c.

193  {
194  step();
195  return EFI_SUCCESS;
196 }
#define EFI_SUCCESS
Enumeration of EFI_STATUS.
Definition: UefiBaseType.h:114
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 211 of file efi_download.c.

211  {
213  EFI_STATUS efirc;
214  int rc;
215 
217  &handle,
220  NULL );
221  if ( efirc ) {
222  rc = -EEFI ( efirc );
223  DBG ( "Could not install download protocol: %s\n",
224  strerror ( rc ) );
225  return rc;
226  }
227 
228  return 0;
229 }
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2081
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:171
EFI_INSTALL_MULTIPLE_PROTOCOL_INTERFACES InstallMultipleProtocolInterfaces
Definition: UefiSpec.h:1996
char * strerror(int errno)
Retrieve string representation of error number.
Definition: strerror.c:78
EFI Boot Services Table.
Definition: UefiSpec.h:1917
static IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface
Publicly exposed iPXE download protocol.
Definition: efi_download.c:199
RETURN_STATUS EFI_STATUS
Function return status for EFI API.
Definition: UefiBaseType.h:31
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:321
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 236 of file efi_download.c.

236  {
238 
240  handle,
243 }
EFI_BOOT_SERVICES * BootServices
A pointer to the EFI Boot Services Table.
Definition: UefiSpec.h:2081
EFI Boot Services Table.
Definition: UefiSpec.h:1917
EFI_UNINSTALL_MULTIPLE_PROTOCOL_INTERFACES UninstallMultipleProtocolInterfaces
Definition: UefiSpec.h:1997
static IPXE_DOWNLOAD_PROTOCOL ipxe_download_protocol_interface
Publicly exposed iPXE download protocol.
Definition: efi_download.c:199
EFI_SYSTEM_TABLE * efi_systab
uint16_t handle
Handle.
Definition: smbios.h:16
#define NULL
NULL pointer (VOID *)
Definition: Base.h:321
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:249
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:194
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:80
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:193
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:176

Publicly exposed iPXE download protocol.

Definition at line 199 of file efi_download.c.

Referenced by efi_download_install(), and efi_download_uninstall().