1158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron/** @file 2158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 3158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron Copyright (c) 2015, ARM Ltd. All rights reserved.<BR> 4158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 5158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron This program and the accompanying materials 6158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron are licensed and made available under the terms and conditions of the BSD License 7158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron which accompanies this distribution. The full text of the license may be found at 8158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron http://opensource.org/licenses/bsd-license.php 9158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 10158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 13158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron**/ 14158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 15158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronThe purpose of the FdtPlatformDxe UEFI driver is to install the Flat Device 16158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronTree (FDT) of the platform the UEFI frimware is running on into the UEFI 17158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronConfiguration Table. The FDT is identified within the UEFI Configuration 183c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronTable by the "gFdtTableGuid" GUID defined in "EmbeddedPkg.dec". 19158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 20158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronOnce installed, an UEFI application or OS boot loader can get from the UEFI 21158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronConfiguration Table the FDT of the platform from the "gFdtTableGuid" GUID. 22158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 23158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronThe installation is done after each boot at the end of the DXE phase, 24158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronjust before the BDS phase. It is done at the end of the DXE phase to be sure 25158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronthat all drivers have been dispatched. That way, all UEFI protocols that may 26158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronbe needed to retrieve the FDT can be made available. It is done before the BDS 27158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronphase to be able to provide the FDT during that phase. 28158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 29158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronThe present driver tries to retrieve the FDT from the device paths defined in the 30158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron"gEmbeddedTokenSpaceGuid.PcdFdtDevicePaths" PCD. The "PcdFdtDevicePaths" PCD 31158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Croncontains a list a device paths. The device paths are in the text form and 32158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronseparated by semi-colons. The present driver tries the device paths in the order 33158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronit finds them in the "PcdFdtDevicePaths" PCD as long as he did not install 34158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronsuccesfully a FDT. 35158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 36158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronThe "PcdFdtDevicePaths" PCD is a dynamic PCD that can be modified during the 37158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronDXE phase. This allows for exemple to select the right FDT when a binary is 38158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronintended to run on several platforms and/or variants of a platform. 39158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 40158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronIf the driver manages to download a FDT from one of the device paths mentioned 41158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronabove then it installs it in the UEFI Configuration table and the run over the 42158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Crondevice paths is stopped. 43158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron 44158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronFor development purposes only, if the feature PCD "gEmbeddedTokenSpaceGuid. 45158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronPcdOverridePlatformFdt" is equal to TRUE, then before to try to install the 46158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald CronFDT from the device paths listed in the "PcdFdtDevicePaths" PCD, the present 47158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Crondriver tries to install it using the device path defined by the UEFI variable 48158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cron"Fdt". If the variable does not exist or the installation using the device path 49158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Crondefined by the UEFI variable fails then the installation proceeds as described 50158497a094dc6b6a2de0c539c1f9c8341aa8b499Ronald Cronabove. 513c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cron 523c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronFurthermore and again for development purposes only, if the feature PCD 533c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cron"PcdOverridePlatformFdt" is equal to TRUE, the current driver provides the EFI 543c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronShell command "setfdt" to define the location of the FDT by the mean of an EFI 553c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronShell file path (like "fs2:\boot\fdt.dtb") or a device path. 563c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cron 573c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronIf the path passed in to the command is a valid EFI Shell file path, the 583c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Croncommand translates it into the corresponding device path and stores that 593c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Crondevice path in the "Fdt" UEFI variable asking for the variable to be non 603c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cronvolatile. 613c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cron 623c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronIf the path passed in to the command is not recognised as a valid EFI 633c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronShell device path, the command handles it as device path and stored 643c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cronin the "Fdt" UEFI variable as it is. 653c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cron 663c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronFinally, the "-i" option of the "setfdt" command allows to trigger the FDT 673c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Croninstallation process. The installation process is completed when the command 683c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cronreturns. The command can be invoked with the "-i" option only and in that 693c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Croncase the "Fdt" UEFI variable is not updated and the command just runs the 703c1e53ce8f52429067a6664576e0bd5611d4e764Ronald CronFDT installation process. If the command is invoked with the "-i" option and 713c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cronan EFI Shell file path then first the "Fdt" UEFI variable is updated accordingly 723c1e53ce8f52429067a6664576e0bd5611d4e764Ronald Cronand then the FDT installation process is run. 73