Qualcomm Technologies, Inc.
Linux Android UEFI Overview
80-P2484-37 C
June 13, 2017
Confidential and Proprietary – Qualcomm Technologies, Inc.
NO PUBLIC DISCLOSURE PERMITTED: Please report postings of this document on public servers or websites to:
DocCtrlAgent@qualcomm.com.
Restricted Distribution: Not to be distributed to anyone who is not an employee of either Qualcomm Technologies, Inc. or its
affiliated companies without the express approval of Qualcomm Configuration Management.
Not to be used, copied, reproduced, or modified in whole or in part, nor its contents revealed in any manner to others without the
express written permission of Qualcomm Technologies, Inc.
Qualcomm is a trademark of Qualcomm Incorporated, registered in the United States and other countries. Other product and brand
names may be trademarks or registered trademarks of their respective owners.
This technical data may be subject to U.S. and international export, re-export, or transfer (“export”) laws. Diversion contrary to U.S.
and international law is strictly prohibited.
Qualcomm Technologies, Inc.
5775 Morehouse Drive
San Diego, CA 92121
U.S.A.
© 2016–2017 Qualcomm Technologies, Inc. All rights reserved.
Revision history
Revision
Date
Description
September 2016
December 2016
June 2017
Initial release
Added note in sections 2.2 and 6.4
Added section 2.8
Updated section 6.4
Added section 6.5
Updated sections 2.8, 3.1, 3.2, 3.3, and 5.2
A
B
C
80-P2484-37 C
Confidential and Proprietary – Qualcomm Technologies, Inc.
2
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Contents
1 Introduction ...................................................................................................... 5
1.1 Purpose.......................................................................................................................... 5
1.2 Conventions .................................................................................................................. 5
1.3 Technical assistance ...................................................................................................... 5
2 UEFI components ............................................................................................ 6
2.1 What is UEFI ................................................................................................................ 6
2.2 Memory allocation services .......................................................................................... 7
2.3 System table .................................................................................................................. 7
2.4 Task priority level (TPL) .............................................................................................. 7
2.5 Events............................................................................................................................ 8
2.6 Re-entrancy ................................................................................................................... 8
2.7 C standard library .......................................................................................................... 8
2.8 Ramdump collection ..................................................................................................... 9
3 QTI UEFI components ................................................................................... 10
3.1 Linux Android UEFI components flowchart .............................................................. 10
3.2 UEFI XBL core directory structure ............................................................................ 11
3.3 UEFI ABL (open source) directory structure ............................................................. 12
3.4 UEFI stages ................................................................................................................. 13
3.5 BDS menu ................................................................................................................... 14
3.6 QTI UEFI protocols .................................................................................................... 15
3.7 QTI UEFI libraries ...................................................................................................... 15
4 UEFI development ......................................................................................... 16
4.1 UEFI application ......................................................................................................... 16
4.1.1 Building and adding a new UEFI application .................................................. 16
4.2 To build a new protocol .............................................................................................. 21
4.3 UEFI/DXE driver ........................................................................................................ 23
5 UEFI build steps ............................................................................................ 28
5.1 For XBL core .............................................................................................................. 28
5.2 For ABL ...................................................................................................................... 28
6 UEFI debugging ............................................................................................. 29
6.1 Debugging using Trace32 scripts ................................................................................ 29
6.2 UEFI app debugging ................................................................................................... 30
6.3 UEFI symbol load scripts............................................................................................ 31
80-P2484-37 C
Confidential and Proprietary – Qualcomm Technologies, Inc.
3
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Linux Android UEFI Overview
Introduction
6.4 UEFI logging .............................................................................................................. 31
6.5 UEFI ramdump collection........................................................................................... 32
6.5.1 UEFI ramdump analysis .................................................................................. 32
6.5.2 UEFI crash ....................................................................................................... 32
A References ..................................................................................................... 34
A.1 Related documents ..................................................................................................... 34
A.2 Acronyms and terms .................................................................................................. 34
80-P2484-37 C
Confidential and Proprietary – Qualcomm Technologies, Inc.
4
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
1 Introduction
1.1 Purpose
This document provides users with the overview of UEFI and how to customize the UEFI module
in Qualcomm Technologies, Inc. (QTI) MSM8998 chipsets.
It also provides details on how to create a UEFI driver of application using opensource or QTI’s
protocols.
1.2 Conventions
Function declarations, function names, type declarations, attributes, and code samples appear in a
different font, for example, #include.
Code variables appear in angle brackets, for example, .
Commands to be entered appear in a different font, for example, copy a:*.* b:.
Button and key names appear in bold font, for example, click Save or press Enter.
Shading indicates content that has been added or changed in this revision of the document.
1.3 Technical assistance
For assistance or clarification on information in this document, submit a case to Qualcomm
Technologies, Inc. (QTI) at https://createpoint.qti.qualcomm.com/.
If you do not have access to the CDMATech Support website, register for access or send email to
support.cdmatech@qti.qualcomm.com.
80-P2484-37 C
Confidential and Proprietary – Qualcomm Technologies, Inc.
5
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
2 UEFI components
QTI is replacing the Little Kernel (LK) Apps Bootloader with a UEFI-based implementation for
Linux Android. Only UEFI is supported on the MSM8998 and later chipsets. LK is the last
remaining 32-bit image and 64-bit support is required to enable direct addressing of all RAM on
devices with more than 4 GB of memory.
UEFI is implemented in two parts:
XBL core contains chipset-specific core protocols (drivers) and core applications (such as
charging)
ABL contains chipset-independent applications such as fastboot
XBL core is part of the non-HLOS boot_images code. ABL is part of the open source Linux
Android source tree on Code Aurora Forum. ABL source is BSD-licensed.
LK device drivers move into XBL core. Leveraging drivers from XBL core reduces code
duplication. The Linux loader and fastboot functionality are refactored as stand-alone UEFI
applications.
The impact to customers transitioning from LK are as follows:
Any OEM modifications to LK are to be ported to XBL Core and ABL.
Access to QTI-specific software drivers are exposed via standard UEFI protocols or protocol
extensions, where necessary.
2.1 What is UEFI
Unified extensible firmware interface (UEFI) is a specification that defines a software interface
between an operating system (OS) and platform firmware. The interface consists of data tables
that contain platform-related information, plus boot and runtime service calls that are available to
the OS and its loader. Together, these provide a standard environment for booting an OS and
running preboot applications.
The UEFI Forum is the group responsible for developing, managing, and promoting UEFI
specifications. For details, check the website at http://www.uefi.org/. The current specification is
Version 2.5.
QTI uses TianocoreEDK2 implementation for the UEFI specification. It is an open source
implementation available at http://www.tianocore.org/edk2/. TianoCore EDK II provides modern,
feature-rich, cross-platform firmware development environment for the UEFI and PI
specifications. It has a BSD License.
QTI is a contributing member of the UEFI forum and adds support for QTI’s SoCs.
80-P2484-37 C
Confidential and Proprietary – Qualcomm Technologies, Inc.
6
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Linux Android UEFI Overview
UEFI components
2.2 Memory allocation services
UEFI supports dynamic memory allocation. Different types of allocations that are possible are as
follows:
Address – Any, Absolute, Max
Type – BS, RT, Code, Data, and so on
Attributes – Cached, Uncached, Device I/O, and so on
UEFI specification does not support uncached allocations. It is handled in the Lib layer to change
the attributes post allocation. Use AllocatePages() to allocate at page granularity. Use
AllocatePool() to allocate at byte granularity.
Since the .efi image contains the ZI region prefilled with zeros, the recommendation is to use
dynamic memory for ZI.
NOTE: Persistent variable storage is not available in UEFI in MSM8998 chipset. This feature will be
added in upcoming chipsets.
2.3 System table
The system table is the root data structure in a UEFI environment. The definition is found in the
UEFI spec. It is the gateway into UEFI services (BS/RT/Misc). The system table makes it
possible for apps to use the services and discover any additional installed services/protocols in the
system.
The system table and image handle are passed to image entry points. Some of the data structures
and tables are installed in configurations passed to the HLOS. The HLOS calls into the RT
services and consumes data structures by dereferencing ST, for example, data structures are ACPI
tables, SMBios.
2.4 Task priority level (TPL)
UEFI supports rudimentary locking using priority levels. There are four common priority levels:
TPL_APPLICATION
TPL_CALLBACK
TPL_NOTIFY
TPL_HIGH
TPL_HIGH priority level disables interrupts. UEFI starts in TPL_APPLICATION priority level.
Code can raise/lower the priorities based on the need of the module. In the case of raising priority
levels, a user can only raise TPL from a lower level to higher. If the user tries to raise TPL to a
level and TPL is already at a higher level, it would result in a crash.
Modules modifying TPL should refer to the specification and confirm the allowed TPL for a
given functionality/layer. Libraries should be careful with selecting the TPL level to raise, since
one of the caller modules might have raised TPL already
80-P2484-37 C
Confidential and Proprietary – Qualcomm Technologies, Inc.
7
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION
Linux Android UEFI Overview
UEFI components
2.5 Events
UEFI supports the following event functionalities:
Create an event.
Destroy an event.
Check to see if an event is in the signaled state.
Wait for an event to be in the signaled state.
Request that an event be moved from the waiting state to the signaled state.
Based on the priority of the sender and receivers, these could be synchronous or asynchronous.
Dispatching mechanism has queues per priority level. All the notifications get into the queues
before dispatcher handles. Dispatching starts from highest priority level queue. Sequences of
events are in LIFO order, register through dispatch “within same dispatch TPL”. Calling into Dxe
services from callbacks complicates the situation because of TPL levels (includes debug print).
Event/callback handlers should be contained small leaf routines.
2.6 Re-entrancy
As per specification, UEFI is single core and single threaded. Because of these even multiple
interrupts are NOT supported, only timer interrupts are supported. Timer ISR is not available
directly as a service. UEFI has a SetTimer function that can issue callback notifications.
UEFI also supports signal notifications and top priority levels (TPL). Signals sent from a different
priority level results in either immediate pre-empt or queued dispatch. Because of the callback
notifications and dispatch, UEFI is strictly not “single threaded” for any code that handles these
notifications/callbacks.
2.7 C standard library
There are several options for C standard library support:
Edk2/Stdlib
CompilerIntrinsicsLib from ArmPkg
Musllib from QcomPkg
CompilerIntrinsicsLib from ArmPkg are used in both XBL Core and abl. Musllib is used
primarily for string routines, and is only available in XBL Core. Edk2/stdlib is only available in
abl.
NOTE: Use the existing C lib, Stdlib, for all requirements. Do not create libs based on the existinf
standard c libs. Integrating such new libs in the UEFi framework might cause issues.
80-P2484-37 C
Confidential and Proprietary – Qualcomm Technologies, Inc.
8
MAY CONTAIN U.S. AND INTERNATIONAL EXPORT CONTROLLED INFORMATION