===========================================
ABL entry point and top-level orchestration
===========================================

This page covers the ABL DXE from its PE entry point through the top-level
``LinuxLoaderEntry`` call sequence, and the ``Board.c`` platform-identification
path it drives — call order only; the individual subsystems it dispatches to
are documented on their own pages and only cross-referenced here (kernel
hand-off → :doc:`/abl/bootlinux`; AVB → :doc:`/abl/verified-boot`;
fastboot → :doc:`/abl/fastboot`; key/boot-mode detection →
:doc:`/boot/keys`; the full function inventory →
:doc:`/abl/function-map`).

RVAs are LinuxLoader-relative (= ABL DXE file offset − ``0xb8``); runtime =
load base + RVA. All addresses below were read from the decompressed DXE
(``../artifacts/abl_a/abl_dxe_fv.bin``); the LinuxLoader PE was carved at DXE
offset ``0xb8`` so that PE file offset == RVA.

PE entry point (``entry0``)
===========================

The PE entry point is at RVA ``0x1000`` (start of ``.text``), a 168-byte
``ModuleEntryPoint`` stub emitted by the EDK2 build (``AutoGen.c``). It performs
the standard UEFI application prologue — set up the stack cookie, then call the
module's real entry — and tail-calls ``LinuxLoaderEntry`` at RVA ``0x12dc``
(direct ``bl`` from ``entry0``). It carries no boot logic of its own.

Basis: ``entry0`` at ``0x1000`` has a single outbound call to ``0x12dc``; the
``0x12dc`` body references the ``LinuxLoaderEntry Address: 0x%llx`` and
``Loader Build Info: %a %a`` debug strings emitted by the real entry function
(:doc:`/abl/container` records the ``.text`` layout and ``ImageBase=0``).

``LinuxLoaderEntry`` (RVA ``0x12dc``)
=====================================

``LinuxLoaderEntry`` is the top-level orchestrator (source:
``QcomModulePkg/Application/LinuxLoader/LinuxLoader.c``). Its call order, read
from the binary and structurally correlated against the matched source (a
version-gapped proxy tag, not a same-version match — see Provenance below), is:

.. list-table::
   :header-rows: 1
   :widths: 6 34 60

   * - #
     - Step (source name)
     - Purpose / binary basis
   * - 1
     - ``InitThreadUnsafeStack`` / ``StackGuardChkSetup``
     - Allocate the thread-unsafe stack and arm the stack cookie. On failure,
       branches straight to the ``stack_guard_update_default`` epilogue.
       Basis: ``Unable to Allocate memory for Unsafe Stack: %r`` string.
   * - 2
     - ``BootStatsSetTimeStamp (BS_BL_START)``
     - Record the boot-stat start timestamp.
   * - 3
     - ``DeviceInfoInit``
     - Initialise verified boot and read ``devinfo`` (lock state). Enforcement
       detail on :doc:`/abl/verified-boot`. Basis:
       ``Initialize the device info failed: %r``.
   * - 4
     - ``EnumeratePartitions`` / ``UpdatePartitionEntries``
     - Enumerate the GPT and build the in-memory partition table. Basis:
       ``LinuxLoader: Could not enumerate partitions: %r``.
   * - 5
     - ``PartitionHasMultiSlot`` / ``FindPtnActiveSlot``
     - Detect A/B and select the active slot (this unit is slot ``a``).
   * - 6
     - ``GetKeyPress``
     - Read the boot-time key. ``SCAN_DOWN`` → fastboot, ``SCAN_UP`` → recovery,
       ``SCAN_ESC`` → ``RebootDevice(EMERGENCY_DLOAD)``. The key-detection
       machine itself is owned by :doc:`/boot/keys`.
   * - 7
     - ``GetRebootReason`` + reboot-mode switch
     - Decode the reboot cookie: ``FASTBOOT_MODE`` / ``RECOVERY_MODE`` /
       ``ALARM_BOOT`` / ``DM_VERITY_ENFORCING`` (→ ``EnableEnforcingMode(TRUE)``)
       / ``DM_VERITY_LOGGING`` (→ ``MdtpDisable`` + ``EnableEnforcingMode(FALSE)``)
       / ``DM_VERITY_KEYSCLEAR`` (→ ``ResetDeviceState``). Basis:
       ``Failed to get Reboot reason: %r``,
       ``Boot reason: 0x%x not handled, defaulting to Normal Boot``.
   * - 8
     - ``RecoveryInit``
     - Fold BCB/misc recovery request into ``BootIntoRecovery`` (non-fatal).
   * - 9
     - ``BoardInit``
     - Populate board/chip/platform data (see `Board identification`_). Fatal on
       error: ``Error finding board information: %r`` → early return.
   * - 10
     - ``GetVmData``
     - Probe for hypervisor VM data; logs ``VM Hyp calls not present`` if absent.
   * - 11
     - ``LoadImageAndAuth`` (when **not** fastboot)
     - Load and AVB-verify boot/dtbo/recovery into a ``BootInfo``. Full path on
       :doc:`/abl/verified-boot`. On failure, falls through to fastboot.
   * - 12
     - ``WaitForDisplayCompletion`` → ``BootLinux``
     - Flush the splash/display, then hand off to the kernel. Hand-off contract
       on :doc:`/abl/bootlinux`.
   * - 13
     - ``FastbootInitialize`` (``fastboot:`` label)
     - Reached when fastboot was selected or ``LoadImageAndAuth`` failed. Basis:
       ``Launching fastboot``. Command surface on :doc:`/abl/container`, handler
       internals on :doc:`/abl/fastboot`.
   * - 14
     - ``stack_guard_update_default`` epilogue
     - Restore ``__stack_chk_guard`` to its default and return.

The observed binary control flow matches this order: the body issues ~15 calls
to the shared debug-print thunk at RVA ``0x2148`` interleaved with the step
calls above, and branches into the key/boot-mode routines at ``0x1964``
(PON reason), ``0x1bfc`` (``BootIntoMode``) and ``0x1e0c``
(``GetBootIntoModeRecovery``).

.. note::

   **Analyzer boundary artifact.** radare2's auto-analysis merges
   ``LinuxLoaderEntry`` with the downstream key/boot-mode-detection cluster into
   one 3700-byte function spanning ``0x12dc``–``0x2150`` (the routines
   :doc:`/boot/keys` documents at ``0x15d0`` / ``0x1638`` /
   ``0x1690`` / ``0x1968`` / ``0x1bfc`` / ``0x1e0c`` are basic blocks inside this
   span, not separate function starts, because control reaches them by
   conditional branch and they share the ``stack_guard_update_default`` tail).
   The logical decomposition is the source's; the merge is noted in the
   deviations/analysis column of :doc:`/abl/function-map`.

.. _Board identification:

Board identification (``Board.c``)
==================================

``BoardInit`` populates the board record that later drives DTB selection,
fastboot ``getvar`` and the kernel command line. Platform identity is obtained
by **runtime UEFI protocol query**, not from any static SoC table compiled into
ABL:

- ``GetChipInfo`` → ``gBS->LocateProtocol (&gEfiChipInfoProtocolGuid …)`` then
  the protocol's chip-id/version/foundry/modem getters. Basis (RVA ``0x12248``,
  Board.c chip-id-string helper): ``Locate Protocol failed for
  gEfiChipInfoProtocolGuid``, ``Failed to Get the ChipIdString``,
  ``Error: HW Platform string is NULL``.
- ``GetPlatformInfo`` → ``gBS->LocateProtocol (&gEfiPlatformInfoProtocolGuid …)``
  then ``hPlatformInfoProtocol->GetPlatformInfo (…, &PlatformInfo)``; the result
  is bounds-checked against ``EFI_PLATFORMINFO_NUM_TYPES``. Basis (RVA
  ``0x11740``, Board.c board-init/dump): ``Error: Failed to locate PlatformInfo
  protocol.``, ``Error: GetPlatformInfo failed.``,
  ``Error: Unknown platform type (%d).``.

``BoardInit`` (RVA ``0x11740``) then logs the resolved identity —
``Raw Chip Id : 0x%x``, ``Chip Version : 0x%x``, ``Foundry Id : 0x%x``,
``Platform Info : 0x%x``, ``HLOS SubType : 0x%x``, ``Fusion Value : %d`` — and
the accessors ``BoardPlatformType`` / ``BoardPlatformChipVersion`` /
``BoardPlatformFoundryId`` / ``BoardTargetId`` read back the cached
``platform_board_info`` struct. Because both identity sources are
``LocateProtocol`` results resolved at run time, ABL carries **no** hard-coded
SM6350 platform-type table; the SoC identity documented in :doc:`/abl/container`
(``lagoon`` / ``msm-id 0x1b2``) is what these protocols return on this unit, not
a constant baked into LinuxLoader.

Provenance
==========

:Source: ``../artifacts/abl_a/abl_dxe_fv.bin`` (decompressed ABL DXE; LinuxLoader
   PE carved at DXE offset ``0xb8`` so PE offset == RVA). Matched upstream source
   for structural correlation only:
   ``QcomModulePkg/Application/LinuxLoader/LinuxLoader.c`` and
   ``QcomModulePkg/Library/BootLib/Board.c`` at CodeLinaro tag
   ``LA.UM.9.12.1.r2-05100-SMxx50.QSSI12.0`` (a QSSI12/Android-12 build; the
   version gap to this Android-11 unit is an open question — see
   :doc:`/abl/function-map` and :doc:`/open-questions`).
:Method: radare2 (base 0) disassembly and call-graph; per-function string
   evidence resolved by decoding AArch64 ``adrp``/``add`` literal pairs with
   Capstone (r2's own xref inference does not resolve these). ``entry0``→
   ``0x12dc`` edge and the ``LinuxLoaderEntry`` call order read from the binary;
   step names correlated to ``LinuxLoader.c`` / ``Board.c``. The
   ``0x12dc`` function-boundary merge is a radare2 auto-analysis artifact, stated
   as such — the binary is unmodified.
:Cross-refs: :doc:`/abl/container` (container layout, ``.text``/``.data`` map),
   :doc:`/abl/bootlinux` (kernel hand-off),
   :doc:`/abl/verified-boot` (``DeviceInfoInit`` / ``LoadImageAndAuth``),
   :doc:`/abl/fastboot` (``FastbootInitialize``),
   :doc:`/boot/keys` (``GetKeyPress`` and the boot-mode machine),
   :doc:`/abl/function-map` (full reachable-function inventory).