EFI LOAD FILE PROTOCOL

From PhoenixWiki

Jump to: navigation, search

Is used to obtain files from arbitrary devices.

Contents

GUID

#define EFI_LOAD_FILE_PROTOCOL_GUID \
  {0x56EC3091,0x954C,0x11d2,0x8E,0x3F,0x00,0xA0,0xC9,0x69,0x72,0x3B}

Protocol Interface Structure

#include EFI_PROTOCOL_CONSUMER(LoadFile)

extern EFI_GUID gEfiLoadFileProtocolGuid;
typedef struct {
  EFI_LOAD_FILE LoadFile;
} EFI_LOAD_FILE_PROTOCOL;

Parameters

LoadFile Causes the driver to load the requested file.

Description

The EFI_LOAD_FILE_PROTOCOL is a simple protocol used to obtain files from arbitrary devices.

When the firmware is attempting to load a file, it first attempts to use the device’s Simple File System protocol to read the file. If the file system protocol is found, the firmware implements the policy of interpreting the File Path value of the file being loaded. If the device does not support the file system protocol, the firmware then attempts to read the file via the EFI_LOAD_FILE_PROTOCOL and the LoadFile() function. In this case the LoadFile() function implements the policy of interpreting the File Path value.

LoadFile()

Causes the driver to load a specified file.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_LOAD_FILE) (
  IN     EFI_LOAD_FILE_PROTOCOL   *This,
  IN     EFI_DEVICE_PATH_PROTOCOL *FilePath,
  IN     BOOLEAN                  BootPolicy,
  IN OUT UINTN                    *BufferSize,
  IN     VOID                     *Buffer OPTIONAL
  );

Parameters

Parameter Member
This Indicates a pointer to the calling context.
FilePath The device specific path of the file to load.
BootPolicy If TRUE, indicates that the request originates from the boot manager, and that the boot manager is attempting to load FilePath as a boot selection. If FALSE, then FilePath must match an exact file to be loaded.
BufferSize On input the size of Buffer in bytes. On output with a return code of EFI_SUCCESS, the amount of data transferred to Buffer. On output with a return code of EFI_BUFFER_TOO_SMALL, the size of Buffer required to retrieve the requested file.
Buffer The memory buffer to transfer the file to. If Buffer is NULL, then no the size of the requested file is returned in BufferSize.

Description
The LoadFile() function interprets the device-specific FilePath parameter, returns the entire file into Buffer, and sets BufferSize to the amount of data returned. If Buffer is NULL, then the size of the file is returned in BufferSize. If Buffer is not NULL, and BufferSize is not large enough to hold the entire file, then EFI_BUFFER_TOO_SMALL is returned, and BufferSize is updated to indicate the size of the buffer needed to obtain the file. In this case, no data is returned in Buffer.

If BootPolicy is FALSE the FilePath must match an exact file to be loaded. If no such file exists, EFI_NOT_FOUND is returned.

If BootPolicy is FALSE, and an attempt is being made to perform a network boot through the PXE Base Code protocol, EFI_UNSUPPORTED is returned.

If BootPolicy is TRUE the firmware’s boot manager is attempting to load an EFI image that is a boot selection. In this case, FilePath contains the file path value in the boot selection option. Normally the firmware would implement the policy on how to handle an inexact boot file path; however, since in this case the firmware cannot interpret the file path, the LoadFile() function is responsible for implementing the policy. For example, in the case of a network boot through the PXE Base Code protocol, FilePath merely points to the root of the device, and the firmware interprets this as wanting to boot from the first valid loader.

The following is a list of events that LoadFile() will implement for a PXE boot:

  • Perform DHCP.
  • Optionally prompt the user with a menu of boot selections.
  • Discover the boot server and the boot file.
  • Download the boot file into Buffer and update BufferSize with the size of the boot file.

Status Codes Returned

Status Code Description
EFI_SUCCESS The file was loaded.
EFI_UNSUPPORTED The device does not support the provided BootPolicy.
EFI_INVALID_PARAMETER FilePath is not a valid device path, or BufferSize is NULL.
EFI_NO_MEDIA No medium was present to load the file.
EFI_DEVICE_ERROR The file was not loaded due to a device error.
EFI_NO_RESPONSE The remote system did not respond.
EFI_NOT_FOUND The file was not found.
EFI_ABORTED The file load process was manually cancelled.
EFI_BUFFER_TOO_SMALL The BufferSize is too small to read the current directory entry. BufferSize has been updated with the size needed to complete

the request.


Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 UEFI Forum, Inc. Used with permission.

Personal tools