EmbeddedPkg: import Lan91x Ethernet controller driver
[mirror_edk2.git] / EmbeddedPkg / Drivers / FdtPlatformDxe / README.txt
CommitLineData
158497a0
RC
1/** @file
2
3 Copyright (c) 2015, ARM Ltd. All rights reserved.<BR>
4
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13**/
14
15The purpose of the FdtPlatformDxe UEFI driver is to install the Flat Device
16Tree (FDT) of the platform the UEFI frimware is running on into the UEFI
17Configuration Table. The FDT is identified within the UEFI Configuration
3c1e53ce 18Table by the "gFdtTableGuid" GUID defined in "EmbeddedPkg.dec".
158497a0
RC
19
20Once installed, an UEFI application or OS boot loader can get from the UEFI
21Configuration Table the FDT of the platform from the "gFdtTableGuid" GUID.
22
23The installation is done after each boot at the end of the DXE phase,
24just before the BDS phase. It is done at the end of the DXE phase to be sure
25that all drivers have been dispatched. That way, all UEFI protocols that may
26be needed to retrieve the FDT can be made available. It is done before the BDS
27phase to be able to provide the FDT during that phase.
28
29The present driver tries to retrieve the FDT from the device paths defined in the
30"gEmbeddedTokenSpaceGuid.PcdFdtDevicePaths" PCD. The "PcdFdtDevicePaths" PCD
31contains a list a device paths. The device paths are in the text form and
32separated by semi-colons. The present driver tries the device paths in the order
33it finds them in the "PcdFdtDevicePaths" PCD as long as he did not install
34succesfully a FDT.
35
36The "PcdFdtDevicePaths" PCD is a dynamic PCD that can be modified during the
37DXE phase. This allows for exemple to select the right FDT when a binary is
38intended to run on several platforms and/or variants of a platform.
39
40If the driver manages to download a FDT from one of the device paths mentioned
41above then it installs it in the UEFI Configuration table and the run over the
42device paths is stopped.
43
44For development purposes only, if the feature PCD "gEmbeddedTokenSpaceGuid.
45PcdOverridePlatformFdt" is equal to TRUE, then before to try to install the
46FDT from the device paths listed in the "PcdFdtDevicePaths" PCD, the present
47driver tries to install it using the device path defined by the UEFI variable
48"Fdt". If the variable does not exist or the installation using the device path
49defined by the UEFI variable fails then the installation proceeds as described
50above.
3c1e53ce
RC
51
52Furthermore and again for development purposes only, if the feature PCD
53"PcdOverridePlatformFdt" is equal to TRUE, the current driver provides the EFI
54Shell command "setfdt" to define the location of the FDT by the mean of an EFI
55Shell file path (like "fs2:\boot\fdt.dtb") or a device path.
56
57If the path passed in to the command is a valid EFI Shell file path, the
58command translates it into the corresponding device path and stores that
59device path in the "Fdt" UEFI variable asking for the variable to be non
60volatile.
61
62If the path passed in to the command is not recognised as a valid EFI
63Shell device path, the command handles it as device path and stored
64in the "Fdt" UEFI variable as it is.
65
66Finally, the "-i" option of the "setfdt" command allows to trigger the FDT
67installation process. The installation process is completed when the command
68returns. The command can be invoked with the "-i" option only and in that
69case the "Fdt" UEFI variable is not updated and the command just runs the
70FDT installation process. If the command is invoked with the "-i" option and
71an EFI Shell file path then first the "Fdt" UEFI variable is updated accordingly
72and then the FDT installation process is run.