1NXP i.MX 8M Series
2==================
3
4The i.MX 8M family of applications processors based on Arm Corte-A53 and Cortex-M4
5cores provide high-performance computing, power efficiency, enhanced system
6reliability and embedded security needed to drive the growth of fast-growing
7edge node computing, streaming multimedia, and machine learning applications.
8
9imx8mq is dropped in TF-A CI build due to the small OCRAM size, but still actively
10maintained in NXP official release.
11
12Boot Sequence
13-------------
14
15Bootrom --> SPL --> BL31 --> BL33(u-boot) --> Linux kernel
16
17How to build
18------------
19
20Build Procedure
21~~~~~~~~~~~~~~~
22
23-  Prepare AARCH64 toolchain.
24
25-  Build spl and u-boot firstly, and get binary images: u-boot-spl.bin,
26   u-boot-nodtb.bin and dtb for the target board.
27
28-  Build TF-A
29
30   Build bl31:
31
32   .. code:: shell
33
34       CROSS_COMPILE=aarch64-linux-gnu- make PLAT=<Target_SoC> bl31
35
36   Target_SoC should be "imx8mq" for i.MX8MQ SoC.
37   Target_SoC should be "imx8mm" for i.MX8MM SoC.
38   Target_SoC should be "imx8mn" for i.MX8MN SoC.
39   Target_SoC should be "imx8mp" for i.MX8MP SoC.
40
41Deploy TF-A Images
42~~~~~~~~~~~~~~~~~~
43
44TF-A binary(bl31.bin), u-boot-spl.bin u-boot-nodtb.bin and dtb are combined
45together to generate a binary file called flash.bin, the imx-mkimage tool is
46used to generate flash.bin, and flash.bin needs to be flashed into SD card
47with certain offset for BOOT ROM. the u-boot and imx-mkimage will be upstreamed
48soon, this doc will be updated once they are ready, and the link will be posted.
49
50TBBR Boot Sequence
51------------------
52
53When setting NEED_BL2=1 on imx8mm. We support an alternative way of
54boot sequence to support TBBR.
55
56Bootrom --> SPL --> BL2 --> BL31 --> BL33(u-boot with UEFI) --> grub
57
58This helps us to fulfill the SystemReady EBBR standard.
59BL2 will be in the FIT image and SPL will verify it.
60All of the BL3x will be put in the FIP image. BL2 will verify them.
61In U-boot we turn on the UEFI secure boot features so it can verify
62grub. And we use grub to verify linux kernel.
63
64Measured Boot
65-------------
66
67When setting MEASURED_BOOT=1 on imx8mm we can let TF-A generate event logs
68with a DTB overlay. The overlay will be put at PLAT_IMX8M_DTO_BASE with
69maximum size PLAT_IMX8M_DTO_MAX_SIZE. Then in U-boot we can apply the DTB
70overlay and let U-boot to parse the event log and update the PCRs.
71
72High Assurance Boot (HABv4)
73---------------------------
74
75All actively maintained platforms have a support for High Assurance
76Boot (HABv4), which is implemented via ROM Vector Table (RVT) API to
77extend the Root-of-Trust beyond the SPL. Those calls are done via SMC
78and are executed in EL3, with results returned back to original caller.
79
80Note on DRAM Memory Mapping
81~~~~~~~~~~~~~~~~~~~~~~~~~~~
82
83There is a special case of mapping the DRAM: entire DRAM available on the
84platform is mapped into the EL3 with MT_RW attributes.
85
86Mapping the entire DRAM allows the usage of 2MB block mapping in Level-2
87Translation Table entries, which use less Page Table Entries (PTEs). If
88Level-3 PTE mapping is used instead then additional PTEs would be required,
89which leads to the increase of translation table size.
90
91Due to the fact that the size of SRAM is limited on some platforms in the
92family it should rather be avoided creating additional Level-3 mapping and
93introduce more PTEs, hence the implementation uses Level-2 mapping which
94maps entire DRAM space.
95
96The reason for the MT_RW attribute mapping scheme is the fact that the SMC
97API to get the status and events is called from NS world passing destination
98pointers which are located in DRAM. Mapping DRAM without MT_RW permissions
99causes those locations not to be filled, which in turn causing EL1&0 software
100not to receive replies.
101
102Therefore, DRAM mapping is done with MT_RW attributes, as it is required for
103data exchange between EL3 and EL1&0 software.
104
105Reference Documentation
106~~~~~~~~~~~~~~~~~~~~~~~
107
108Details on HABv4 usage and implementation could be found in following documents:
109
110- AN4581: "i.MX Secure Boot on HABv4 Supported Devices",  Rev. 4 - June 2020
111- AN12263: "HABv4 RVT Guidelines and Recommendations", Rev. 1 - 06/2020
112- "HABv4 API Reference Manual". This document in the part of NXP Code Signing Tool (CST) distribution.
113
114