AN13275

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
Rev. 1 — 26 May 2023

Application note

Document Information
Information

Content

Keywords

iMX8, Linux BSP, port

Abstract

This application note introduces a general procedure of how to enable standard Linux BSP L5.4
on a new customized i.MX8/8X board.

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

1 Introduction
1.1 Purpose
This application note introduces a general procedure of how to enable standard Linux BSP L5.4 on a newcustomized i.MX 8/8X board. This document can help users, who have designed a customized i.MX 8/8X board,
to quickly port standard Linux BSP release code running on their board and be aware of those key parts thatneed modifications.

1.2 Example board
This application note uses an i.MX 8QXP reference board for automotive as an example board, because thestandard Linux BSP release does not support this board. For more details, contact NXP representative.
The hardware design of the board is based on i.MX 8QXP MEK board, but with the following changes:• i.MX 8QXP C0 Silicon• Samsung auto LPDDR4 and eMMC5.1• MIPI-CSI with NVP6324 automotive AHD solution• LVDS display with TI DS90UB947/948 SerDes (through FPD-Link III) for automotive application• MIPI-DSI display with Maxim 96752/96755 SerDes (through GMSL2) for automotive application• NXP TJA1101 automotive 100 Mbps Ethernet PHY• USB3.0 host for Carplay/AA and USB2.0 OTG for debug

Figure 1. i.MX 8QXP reference board for automotive

1.3 Linux BSP releases
This application note uses the L5.4.47_2.2.0 Linux BSP release as example. For all i.MX Linux BSP releases,
see Embedded Linux for i.MX Applications Processors.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

2 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
The following chapters introduce the general procedure for porting SCFW, ATF, U-Boot, and Linux Kernel. Eachof them can be compiled independently, and the release package or source code can be downloaded fromfollowing links:• SCFWhttps://www.nxp.com/webapp/Download?colCode=L5.4.47_2.2.0_SCFWKIT-1.6.0&appType=license• Arm Trusted Firmware (ATF)
Git clone https://github.com/nxp-imx/imx-atf -b rel_imx_5.4.47_2.2.0• U-Boot
Git clone https://github.com/nxp-imx/uboot-imx -b rel_imx_5.4.47_2.2.0• imx-mkimage
Git clone https://github.com/nxp-imx/imx-mkimage -b rel_imx_5.4.47_2.2.0• Linux Kernel
Git clone https://github.com/nxp-imx/linux-imx -b rel_imx_5.4.47_2.2.0

2 Generating DDR configuration files
The i.MX 8/8X DDR Register Programming Aid (RPA) is an Excel spreadsheet tool used to develop DDR
initialization for the specific DDR configuration (DDR device type, density, and so on). The RPA generates the
DDR initialization in two formats (in separate Excel worksheet tabs):• DDR Stress Test script
This format is used specifically with the DDR stress test by first copying the contents on the DDR Stress Test
Script CBT tab and then pasting it to a text file, naming the document with the .ds file extension. Use this filewhen executing the DDR stress test.
• DCD CFG file
This format is the configuration file used specifically by the SCU Firmware (SCFW). In this scenario, the user
copies the contents on the DCD CFG file CBT tab and pastes it to a text file, naming the document with the.cfg file extension and placing this file in the appropriate SCFW board file directory.

2.1 Downloading RPA tools
Note: In all cases, the RPA revision is aligned to a minimum SCFW version as shown in the table on i.MX 8/8X
Family DDR Tools Release. In some cases, the BSP alignment is provided as extra details.
To obtain the latest RPAs, see the following links:• i.MX8QM DDR Register Programming Aid (RPA)• i.MX8QXP/DXP/DX DDR Register Programming Aid (RPA)
To align with the L5.4.47_2.2.0 BSP and SCFW 1.6.0, use MX8QXP_C0_B0_LPDDR4_RPA_1.2GHz_v14.xlsx
RPA version in the below steps.

2.2 Using RPA tools
To use RPA tools to generate a new DDR stress test script and DCD CFG file for the specific DDR on usercustomized board, perform the following steps.
1. Obtain the desired DDR data sheet from the DDR vendor
To fill the DRAM parameters in the RPA tools, use the DDR data sheet from the DDR vendor. Usually thisdata sheet can be downloaded from the website of the DDR vendor. Users can also contact DDR vendor
directly to request this data sheet.
2. Update the Device Information table on the Register Configuration tab.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

3 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

Figure 2. i.MX8QXP RPA tool register configurations

In the Device information table highlighted in Figure 2, update the following information:• Manufacturer• Memory part number• Density per channel per chip select (GB)• Number of Chip Selects used
• Number of ROW Addresses• Number of COLUMN Addresses• Number of BANK addresses• Bus Width• Clock cycle Freq (MHz)Other parameters are automatically calculated and filled in the table using the information above.
3. Update data bus mapping on the BoardDataBusConfig tab.

Figure 3. i.MX 8QXP RPA tool BoardDataBusConfig

Usually the physical connection of data pins between DDR device and SOC is not a direct match due tophysical layout constraint. Therefore, we need a mapping table to record the physical connection of DDR
data pins, and put this information into the register of DDR controller, so that it can make correct logic
connections of DDR data pins.
In the row highlighted in Figure 3, update the physical mapping of data pins between DDR device and SOC,
according to their hardware schematic. Other parameters are updated automatically according to user input.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

4 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
For example, from the example board schematic in Figure 4, we can find that the DQ0_A pin on DDR
devices is connected to DDR_DQ13 pin on iMX8QXP, so we type 13 in the circled cell and for others, follow
the same method.

Figure 4. Connection of DDR data pins in example board schematic

4. Copy text on the DCD CFG file CBT and DDR Stress Test Script CBT tabs to file.
Click the DCD CFG file CBT tab in RPA tool and copy all the text into a file, naming it as
BOARD_NAME.cfg. This file is used later when porting SCFW.
Click the DDR Stress Test Script CBT tab and copy all the text into a file, naming it as BOARD_NAME.ds.
This file is used in the DDR stress test later.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

5 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

3 SCFW porting
The System Controller Unit (SCU) provides an abstraction to many underlying features of the hardware.
The software running on SCU is known as SC firmware (SCFW). SCFW provides the following features andservices.
• System Initialization and Boot
• System Controller Communication• Power Management• Resource Management• Pad Configuration• Timers• Interrupts• Security• Miscellaneous
Most SCFW codes are provided only in the object file format in SCFW porting kit and users cannot modify. But
for board-related settings, SCFW porting kit has provided the source code of board.c file, which includes boardrelated initialization functions and customized features. This chapter focuses on how to port the board.c file for a
new board.

3.1 Extracting SCFW code
To extract SCFW code, perform the following steps.
1. Download the SCFW 1.6.0 package, imx-scfw-porting-kit-1.6.0.tar.gz, from Apps.
2. Unzip the file.
3. Go to the packages folder.
4. Extract SCFW code with the following command.
$chmod a+x imx-scfw-porting-kit-1.6.0.bin$./imx-scfw-porting-kit-1.6.0.bin
5. After reading and accepting the license, extract the SCFW code in the imx-scfw-porting-kit-1.6.0 folder.
Besides the code, there are release documents extracted in the imx-scfw-porting-kit-1.6.0/doc/pdf folder,
including release note, api user guide, and a more detailed porting guide. For new users and developers of
i.MX8/8X product, these documents are very useful. It is highly recommended to check these documents
first when you have questions about SCFW.
6. Use the following command to extract SCFW code specific for i.MX8QXP.
$cd imx-scfw-porting-kit-1.6.0/src/$tar zxvf scfw_export_mx8qx_b0.tar.gz
The code is in the path of imx-scfw-porting-kit-1.6.0/src/scfw_export_mx8qx_b0/.
We can set this path as SCFW_DIR.

3.2 Creating a board file
Each board has its own special hardware design and may have different board operations in SCFW level.
Therefore SCFW provides a board folder under SCFW_DIR/platform/board/ for every supported board.

The board folder contains following components:
AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

6 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board• board.bom: Includes PMIC driver info
• board.c: Board related operations• board.h: The header file of board.c, including macro definitions used in board.c• Makefile: The makefile for compiling of board.c• dcd/: The folder of DDR configuration files, usually containing at least two scripts as below:– ddr_stress_test_parser.cfg: Used for compiling SCFW for DDR stress test.
– BOARD_NAME.cfg: The ddr script generated in Section 2.2 and used for compiling SCFW for the normal
system use.
To simplify the porting effort, users can directly copy those files from the reference board folder, mx8qx_mek,
and make modifications according to their own specific requirement.
Since the modification is highly related to board design and the use case of the final product, this document
does not list detailed modifications. The following three examples are often customized in the board.c file of theuser.
1. In the board_system_config() function
One major feature that the SCFW provides is resource partitioning. It partitions resources into
different domains to protect system. By default, we create a partition for the M4 core, performed in theboard_system_config() in board.c.
In general, the resource partitioning of M4 follows these steps:
a. Mark all resources as not movable.

b. Create a partition for M4 core.

c. Mark all resources and pad that belong to M4 subsystem as movable.

d. Mark resources and pad that M4 core must use as movable.
Usually this part need modification according to board design and use case.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

7 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

e. Move all resources and pads that have been marked as movable to M4 partition.

f. Assign memory region for M4 partition.
Adjust the memory region in DDR according to the DRAM size of the board.

g. Grant permissions for other partitions to access resources of M4.
This part can also be customized depending on use case.

For the detailed descriptions of the SCFW API used above, see Chapter 16 in sc_fw_port.pdf.
2. In the board_ioctl() function
In certain use case, add the board level function or feature implementation of the user in SCFW. The
board_ioctl() function in board.c is a good place to do so.

Use the SCFW API, sc_misc_board_ioctl, from Linux or M4 to get into board_ioctl() function inboard.c.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

8 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

The sc_misc_board_ioctl() function is passed almost directly to the board_ioctl() function. Threeparameters are passed and returned by pointer and an error code is returned. Users can define meaning
for these three parameters, and implement their own features in the board_ioctl() function. This callis not associated to any resource so there is no security. The MU the API call came from is passed in andthe partition number that owns that MU is also passed in. These can be used to implement some kind of
security.
3. In the board_parameter() function
The board_parameter() function in board.c, as its name implies, is used for configuring board levelparameters. It includes PCIe PLL clock source, settings for KS1 mode and spread spectrum feature fordisplay.
Modify the return value for each parameter to choose desired configuration for their board. For example, touse external clock as the source clock of PCIe PLL, set board_parameter() as below:

To use internal clock as the source clock of PCIe PLL, set board_parameter() as below:

For all available parameter settings, see Chapter 4.4.1 Board Parameters in sc_fw_port.pdf, or the header
file in SCFW_DIR/platform/main/board.h.

3.3 Compiling SCFW
To compile SCFW, perform the following steps:
1. Set building environment
SCFW builds are compiled with a cross compiler in Linux environment. The toolchain for compiling should
be obtained from GNU Arm Embedded Toolchain Downloads. The version used is the GNU Arm Embedded
Toolchain: 8-2018-q4-major December 20, 2018. Download the toolchain source and follow instructions to
install the toolchain on the host Linux machine.
After the installation, the environment variable, TOOLS, must be set to the directory containing the compiler
directory. For example, if using the GCC 4.9 cross-compile tools chain and installing to /home/example/gccarm-none-eabi-8-2018- q4-major, set TOOLS to /home/example. Building also requires srec_cat, found in
the Linux srecord package. Optionally the cppcheck package is also useful.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

9 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
If using bash, then set the TOOLS environment variable as follows:$export TOOLS=<your path to dir holding the toolchain>
2. Compile the code
The SC firmware can be fully compiled using the Makefile. The command format is:
Usage: make TARGET OPTIONSSCFW targets are based on the die, not the part number. Some parts are phantoms of other die (forexample QP is a phantom of QM) created by fusing options. The SCFW supports phantoms at runtime,reading the fuses and adapting. There are three primary die targets:• qm: i.MX8QM die• qx: i.MX8QX die• dxl: i.MX8DXL die
They generate the image (scfw_tcm.bin) in their respective build directory. Table 1 lists options that can be
specified on the make command line.
Table 1. Options on make command line
OptionActionV=0quiet output (default)

V=1

verbose output

D=0

configure for no debug

D=1

configure for debug (default)

DL=<level>

configure debug level (0-5)

M=0no debug monitor (default)

M=1

include debug monitor

B=<board>

configure board (default=val)

U=<uart>configure debug UART (default=0)

DDR_CON=<file>specify DDR configuration file w/o extension

R=<srev>

silicon revision

T=<test>run tests rather than boot next coreThis application note uses an i.MX8QXP board for automotive as an example board, so the board folder
name is mx8qx_auto and DDR script name is imx8qxp_auto_samsung3GB_1.2GHz_v14.cfg. The compile
command is:$make qx R=b0 B=auto M=1 U=2 DDR_CON=imx8qxp_auto_samsung3GB_1.2GHz_v14
Note: For MX8QX, the R=b0 applies to both B0 and C0 silicon revisions. In other words, even if you arebuilding for and using C0 silicon, you still use R=b0.
If the compilation is successful, the SCFW binary can be found in the path of SCFW_DIR/build_mx8qx_b0/
scfw_tcm.bin.
Note:
DDR stress test in Section 4, an SCFW with special DDR script ddr_stress_test_parser.cfg isneeded. Therefore, besides the standard SCFW, users must compile a special SCFW for DDR stress testwith following command:$make qx R=b0 B=auto DDR_CON=ddr_stress_test_parser

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

10 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

4 Running a DDR stress test
MX8 DDR stress test is a software application to verify DDR interface on i.MX8 series boards. It is a program
running on the PC side which downloads a test image to the internal RAM of i.MX series processors through a
USB connection. To access Windows Registry, user must run it in administrator mode. The test image runningon the target board executes the DDR stress test. The result is sent to the PC via the A-core UART and isdisplayed in the log window. There is also an option to save the output to a log file.
MX8 DDR Stress Test can help verify DDR stability on the board in a non-OS environment.
To run the DDR Stress Test Tool, perform the following steps:
1. Download the DDR stress test tool from i.MX 8/8X Family DDR Tools Release.
After being downloaded and installed, the tool can be found in the mx8_ddr_stress_test_ER14 folder under
the install path. For more details about DDR stress test tool, see MX8_DDR_Tool_User_Guide.pdf.
For more details about DDR stress test tool, see MX8_DDR_Tool_User_Guide.pdf.

Figure 5. MX8 DDR Stress Test Tool user interface

2. Prepare the following two files:• The DDR script for DDR stress test
This file is generated in Step 4 in Section 2.2. In this case, the name of the DDR script is
imx8qxp_auto_board.ds and the file can be put in the mx8_ddr_stress_test_ER14\script\mx8qx\imx8qxp_
auto_board.ds folder.
• The special SCFWThis file is generated in Section 3.3, with DDR script, ddr_stress_test_parser.cfg. Rename the
SCFW binary file from scfw_tcm.bin to mx8qxb0_scfw_download.bin and replace the file in the tool folder,
mx8_ddr_stress_test_ER14\bin\mx8qxb0_scfw_download.bin.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

11 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
Note: For MX8QX, this name applies to both B0 and C0 silicon revisions. In other words, even if you arebuilding for and using C0 silicon, you must rename the scfw_tcm.bin as mx8qxb0_scfw_download.bin.
3. Connect the target board to PC host.
a. Configure the i.MX target board to boot in serial download mode/Manufacture mode and power up theboard.
b. Connect a UART cable from the host computer to the MX8 debug UART. For Win10, may require
manually installing COM port driver (FTDI, SiLabs,…)c. Connect a USB cable from the host computer to the USB OTG port on the MX8 target board. An
HID-compliant device or USB input device is shown in the Device Manager. For the MX8 USB OTG
connection, the USB cable must be connected directly to the Host PC USB port and not through a USB
HUB.
4. Launch the MX8_DDR_Tester.exe in the tool folder.
Note: For Win10, right-click MX8_DDR_Tester.exe and select Run as administrator to view and select theavailable COM ports.
5. Press the Search button in the Debug UART area, choose the correct UART port connected to the MX8
Cortex A-Core Debug UART, and press the Connect button.
Note: To view and select the available COM port, run the DDR stress test in administrator mode.
6. Load DDR initialization script and choose correct downloading options.
In this example, we choose the script in the path of mx8_ddr_stress_test_ER14\script\mx8qx\imx8qxp_
auto_board.ds.
7. Press the Download button and wait for target board to be ready.
If the target board boots successfully, DDR initialization information is present on the console of the tool.
8. Press the Stress Test button, with all default settings: default DDR frequency, cache enabled, one loop
DDR stress test, stop when encounter error.
If the board passes the DDR stress test successfully, the Success: DDR Stress test completed!!! log isshown as below:

9. Select Over Night Test, press the Stress Test button again, and the infinite loop of DDR stress test starts.
To increase the confidence on the DDR stability, the board must pass DDR stress test for more than 12hours and repeat the same test in high/low temperature.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

12 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

5 ATF porting
ATF is a reference implementation of secure world software for Arm A-Profile architectures (Armv8-A andArmv7-A), including an Exception Level 3 (EL3) Secure Monitor. It provides a suitable starting point for
production of secure world boot and runtime firmware, in either the AArch32 or AArch64 execution states.
ATF implements Arm interface standards, including:• Power State Coordination Interface (PSCI)• Trusted Board Boot Requirements CLIENT (TBBR-CLIENT)• SMC Calling Convention• System Control and Management Interface (SCMI)• Software Delegated Exception Interface (SDEI)The code is portable and reusable across hardware platforms and software models that are based on the
Armv8-A and Armv7-A architectures. Users are encouraged to do their own security validation, including
penetration testing, on any secure world code derived from ATF.
For i.MX8 chips, ATF is required for all i.MX8 boards. Usually two parts might need customization when porting
for a new board: power management and resource partitioning.

5.1 Power management
As mentioned above, ATF provides PSCI for Linux system to call as power management mechanism. Each
SOC platform can have its own platform-specific PSCI implementation. Below takes the PSCI implementation of
i.MX8QXP as an example.
After following Section 1.3 to download ATF source code to the arm-trusted-firmware folder, the PSCI
implementation code of i.MX8QXP is in arm-trusted-firmware/plat/imx/imx8qx/imx8qx_psci.c.
As shown below, all PSCI operations specific to iMX8QXP platform is defined in the imx_plat_psci_ops
structure and mapped to each implementation function.

Most functions are implemented in this file. Most operations are calling SCFW API to do the power-related
operations, because SCU in i.MX8 architecture controls the power domain of all subsystems. If users havespecific requirement for a certain power mode, they can modify the implementation function here.
For some other i.MX8 common functions like system_off and system_reset, the implementation function
can be found in arm-trusted-firmware/plat/imx/common/imx8_psci.c.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

13 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

One possible modification that users may need is in the imx_system_reset function. By default, theimx_system_reset function calls sc_pm_reboot SCFW API to do partition reboot, which means only thepartition of A core is rebooted and the partition of M4 is not affected.

But in some use cases, user may need the whole board to be reset when Linux system is reset. In
such situation, use sc_pm_reset SCFW API instead of sc_pm_reboot in the imx_system_resetfunction. However, only the owner of the SC_R_SYSTEM resource or a partition with access permissions to
SC_R_SYSTEM can call sc_pm_reset to reset the whole board.

5.2 Resource partitioning
For i.MX8 chips, besides power management, another important role of ATF is to create resource partitions fornon-secure world of A cores. Take i.MX8QXP as an example, this work is done in arm-trusted-firmware/plat/imx/
imx8qx/imx8qx_bl31_setup.c, in the imx8_partition_resourcesfunction.
The process of creating and assigning resources to non-secure world partitions in ATF is similar to the process
for M4 in Section 3.2. In general, performs the following steps:
1. Create a partition for non-secure world and set the parent as ATF partition.
AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

14 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

2. Mark all resources that must be kept in ATF partition as non-movable.

The secure_rsrcs[] array is defined in arm-trusted-firmware/plat/imx/imx8qx/include/sec_rsrc.h andcontains resources that are going to stay in ATF partition. If users have specific requirement, it can be
modified.
3. Allocate memory region for non-secure world. Depending on whether there is OP-TEE or Trusty
implemented, the memory region changes accordingly.
Note:
When OP-TEE is implemented,• If the DRMA size is equal to or greater than 2 GB, by default, the memory region 0xFE000000 –0xFFFFFFFF is used by OP-TEE. This value is set in arm-trusted-firmware/ plat/imx/imx8qx/ platform.mkwith BL32_BASE and BL32_SIZE.
• If the DRAM size of the new board is less than 2 GB, modify BL32_BASE to the highest memory address– BL32_SIZE. For example, if DRAM size is 1 GB, BL32_BASE is 0xBE000000.
4. Move all movable resources and pins to non-secure world partition.

5. Grant access of certain sources to non-secure world partition.

5.3 Compiling ATF
To compile ATF, perform the following steps:
1. Set building environment
The toolchain used to compile ATF is same cross-compile toolchain used for compiling U-Boot and Linuxkernel in the later Chapter. For how to generate and install the toolchain, see Chapter 4.5.12 How to build
U-Boot and Kernel in standalone environment in i.MX Linux User's Guide (document IMXLUG).

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

15 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
https://www.nxp.com/webapp/Download?colCode=L5.4.47_2.2.0_LINUX_DOCS
2. Compile the code
• Use the following command to compile ATF if OP-TEE is not implemented.
$ make PLAT=imx8qx bl31
• Use the following command to compile ATF if OP-TEE is implemented.
$ make PLAT=imx8qx SPD=opteed bl31
If the compilation is successful, the binary file is located in arm-trusted-firmware/build/imx8qx/release/bl31.
bin.
3. Enable debug print
By default, the debug print is not enabled in ATF. To enable debug print, change DEBUG_CONSOLE andDEBUG_CONSOLE_A35 to be defined as 1 in arm-trusted-firmware/ plat/imx/imx8qx/include/platform_def.h.
Compile ATF with the following command.
$ make DEBUG=1 PLAT=imx8qx SPD=opteed bl31
The binary file is in arm-trusted-firmware/build/imx8qx/debug/bl31.bin.

6 U-Boot porting
The Universal Bootloader (shortened as U-Boot) is an open source and primary bootloader used in embedded
devices. It packs the instructions to boot the operating system kernel of the device.
U-Boot is both a first-stage and second-stage bootloader. It is loaded by the ROM of the system or the BIOS²
from a supported boot device, such as, an SD card, SATA drive, NOR flash (such as, using SPI or I C), or
NAND FLASH. If there are size constraints, U-Boot splits into stages:• The platform loads a small Secondary Program Loader (SPL), which is a stripped-down version of U-Boot.
• The SPL initializes hardware configuration and loads the larger, fully featured version of U-Boot.
Regardless of whether the SPL is used, U-Boot performs both first-stage (such as, configuring memory
controllers and SDRAM) and second-stage booting (performing multiple steps to load a modern operating
system from various devices that must be configured, presenting a menu for users to interact with and control
the boot process, and so on).
i.MX8 chips support both SPL or non-SPL U-Boot. In Linux BSP L5.4.47_2.2.0 and later release, the SPL isenabled as default.

6.1 Creating files for a new board
After following steps in Section 1.3, download the U-Boot source code to the uboot-imx folder.
To port U-Boot for a new board, create files listed in Table 2 for the new board. To save the porting effort, users
can copy files from those files for MEK reference board and make modifications according to their own specificrequirement.
In the following context, use imx8qxp_auto as the board name for files created for our new board. Users canmodify the filename for their own board.
Table 2. Files needed for a new board in U-Boot
File location

Description

configs/imx8qxp_auto_defconfig

The defconfig file for auto board

board/freescale/imx8qxp_auto/

The board folder for auto board

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

16 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
Table 2. Files needed for a new board in U-Boot...continued
File location

Description

board/freescale/imx8qxp_auto/Kconfig

The Kconfig file for auto board

board/freescale/imx8qxp_auto/Makefile

The makefile for C files in auto board folder

board/freescale/imx8qxp_auto/imx8qxp_auto.c

The board file that implements board-related initialization
functions, such as, board_init()board/freescale/imx8qxp_auto/imximage.cfg

The file used for configuring imx8 boot image

board/freescale/imx8qxp_auto/spl.c

The file for board-related implementation for SPL bootboard/freescale/imx8qxp_auto/uboot-container.cfg

The file to create a container image that SPL can load

include/configs/imx8qxp_auto.h

The header file for auto board

arch/arm/mach-imx/imx8/ snvs_security_sc_conf_8qxp_auto.
h

The header file of snvs security configuration of autoboard

arch/arm/dts/fsl-imx8qxp-auto.dts

The device tree file for auto board

arch/arm/dts/fsl-imx8qxp-auto-u-boot.dtsi

The device tree including files used for generating dts for
SPL. For details, see doc/README.SPL.

6.2 Modifying files for a new board
To modify files for a new board, perform the following steps:
1. Modify a few existing files to include new board in U-Boot.
a. In arch/arm/mach-imx/imx8/Kconfig, add TARGET_IMX8QXP_AUTO and the Kconfig file of the auto
board.

b. In arch/arm/dts/Makefile, add dtb file for auto board.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

17 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

c. In arch/arm/mach-imx/imx8/snvs_security_sc_conf_board.h, add include for the snvs security
configuration header file of the auto board.

2. Make necessary modifications in those created files. In some files, the modification effort is minor, such as,changing board names and file path. This document does not show all detailed modifications but focuses on
aspects that users usually need more attention and consideration for their own board implementation.
a. In configs/imx8qxp_auto_defconfig
The defconfig file is an important configuration file during compilation, which defines modules that theboard requires.
Taking our auto as example, comparing to the defconfig file of the MEK board. Make the followingchanges in the defconfig file of auto board.
-CONFIG_IMX_CONTAINER_CFG="board/freescale/imx8qxp_mek/ubootcontainer.cfg"-CONFIG_TARGET_IMX8QXP_MEK=y-CONFIG_SYS_EXTRA_OPTIONS="IMX_CONFIG=board/freescale/imx8qxp_mek/
imximage.cfg"-CONFIG_DEFAULT_DEVICE_TREE="fsl-imx8qxp-mek"+CONFIG_IMX_CONTAINER_CFG="board/freescale/imx8qxp_auto/ubootcontainer.cfg"+CONFIG_TARGET_IMX8QXP_AUTO=y+CONFIG_SYS_EXTRA_OPTIONS="IMX_CONFIG=board/freescale/imx8qxp_auto/
imximage.cfg"+CONFIG_DEFAULT_DEVICE_TREE="fsl-imx8qxp-auto"
Besides these changes, there are also changes related to board design or requirement.
For example, on our auto board, the USB 3.0 port is only used as Host mode. Remove its support for
Gadget mode in defconfig as below:-CONFIG_USB_CDNS3_GADGET=y+#CONFIG_USB_CDNS3_GADGET=y
Note: By default, the U-Boot reserves 128 MB memory region for M4 program to use, from
0x88000000 to 0x90000000. This value is defined by CONFIG_BOOTAUX_RESERVED_MEM_BASE andCONFIG_BOOTAUX_RESERVED_MEM_SIZE in defconfig. To change the size of memory region for M4
program to use, modify this CONFIG and the memory region assignment in Section 3.2.
For features and drivers to enable on their new board, add related CONFIG to the defconfig file of theboard.
b. In board/freescale/imx8qxp_auto/imx8qxp_auto.c
AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

18 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
This file contains board-related initialization functions like board_init(). Users can implement
their own board-specific initialization function here or modify existing initialization function for various
modules.
For example, if users have GPIO pins to be set during initialization, add these GPIO pins inboard_gpio_init() function. Then users must use dm_gpio_lookup_name() to find the target
GPIO, use dm_gpio_request() to request the GPIO, use dm_gpio_set_dir_flags() to set
direction and flags of the GPIO pin, and finally use dm_gpio_set_value() to set the output value oftarget GPIO.

c. In include/configs/imx8qxp_auto.h
This header file of board contains many board-related macro definitions. Two most common parts to bemodified are DRAM size and ENV settings.
The DRAM size is defined by:#define PHYS_SDRAM_1 0x80000000#define PHYS_SDRAM_2 0x880000000#define PHYS_SDRAM_1_SIZE 0x80000000 /* 2 GB */#define PHYS_SDRAM_2_SIZE 0x40000000 /* 1 GB */The PHYS_SDRAM_1 defines lower base address of DRAM, and PHYS_SDRAM_2 defines higher baseaddress. The total DRAM size is PHYS_SDRAM_1_SIZE + PHYS_SDRAM_2_SIZE.
If the DRAM size is less than 2 GB, then PHYS_SDRAM_2_SIZE is 0.
Users must modify the define value of PHYS_SDRAM_1_SIZE and PHYS_SDRAM_2_SIZE according to
the DDR device on their board.
As for ENV settings, there are many ENV settings already been defined in the header file. Users can
add new ENV settings in CONFIG_EXTRA_ENV_SETTINGS, and modify existing ENV settings, such as,
fdt_file and mmcargs depending on their own requirement.
The ENV settings can also be changed dynamically in U-Boot console with setenv and saveenv
command.
d. In arch/arm/dts/fsl-imx8qxp-auto.dts
The device tree architecture is first introduced in Linux kernel and implemented in U-Boot. The dts fileis a data structure describing the hardware components of the board so that the system can use andmanage those components.
Users can add or delete device node according to their board design to modify parameters of somedevice nodes, such as, clock frequency and control pins.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

19 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
For SPL, there is also a device tree. To reduce the size of SPL, keep only the nodes with pre-relocation
properties (u-boot, dm-pre-reloc, u-boot, dm-spl) in their device trees. Users can check arch/
arm/dts/fsl-imx8qxp-mek-u- boot.dtsi as an example.

6.3 Compiling U-Boot
1. Set building environment
The toolchain used to compile U-Boot is same cross-compile toolchain in Compiling ATF. For how to
generate and install the toolchain, see Chapter 4.5.12 How to build U-Boot and Kernel in i.MX Linux
User's Guide (document IMXLUG).
https://www.nxp.com/webapp/Download?colCode=L5.4.47_2.2.0_LINUX_DOCS
2. Compile the code
To build the U-Boot for the target board, perform the following steps:
a. Use the following command to generate configuration file for the board. The imx8qxp_auto board isused as an example.
$ make imx8qxp_auto_defconfig
b. Use the following command to generate U-Boot for the target board. The SPL image is generated if
CONFIG_SPL is selected in the configuration file.
$ make -j8
The U-Boot image is put in uboot-imx/u-boot.bin and SPL image is in uboot-imx/spl/u-boot-spl.bin.

7 Building flash.bin image
For i.MX8 chips, the flash.bin image, which is actually the boot image container set, can include SCFW,SECO FW, M4 image, ATF image, U-Boot image, and SPL image. ROM code reads the flash.bin image
from the boot device and loads it to different memory address according to settings.
To simplify the process of generating flash.bin image, use the imx-mkimage tool to combine the images above
to produce the final flash.bin boot image and burn to the boot device.

7.1 Copying images to mkimage
After following steps in Section 1.3, download the imx-mkimage source code in the imx-mkimage folder. The
content includes folders for all supported i.MX8 chips.

To generate the flash.bin image, copy all required images into the folder of the target chip. Taking our
imx8qxp auto board as an example, follow the steps as below.
1. Copy SCFW scfw_tcm.bin generated in Section 3.3 to the imx-mkimage/iMX8QX/ folder.
2. Copy SECO FW mx8qxc0-ahab-container.img to the imx-mkimage/iMX8QX/ folder. Use the following
command to download the image:$wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/imx-seco-3.7.1.bin$chmod a+x imx-seco-3.7.1.bin$cd imx-seco-3.7.1/firmware/seco/For each BSP release, there is an SECO FW version coupled with the release. For how to get the correct
SECO FW version, see i.MX Linux Release Notes (document IMXLXRN).
3. Copy ATF image bl31.bin generated in Section 5.3 to the imx-mkimage/iMX8QX/ folder.
AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

20 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
4. Copy U-Boot image u-boot.bin and SPL image u-boot-spl.bin generated in Section 6.3 to the imxmkimage/ iMX8QX/ folder.
5. Copy M4 image to the imx-mkimage/iMX8QX/ folder, if there is M4 program, and name it as m4_image.bin.
For how to compile M4 images, see MCUXpresso SDK Builder.

7.2 Checking makefile
The makefile for flash.bin image is in imx-mkimage/iMX8QX/soc.mak. By default, many targets have been
defined for common use case. If the target meets their requirement, user can use these targets to build their
flash.bin image directly, or modify the options in these targets, or create a target for their specific need. The
below are some examples.
• flashThe flash target includes SCFW, SECO FW, ATF, and U-Boot image. The ATF image bl31.bin combinedwith u-boot.bin image generate the u-boot-atf.bin.

Since the flash target does not include SPL image, the A core booting address is 0x80000000, as shown
above.
• flash_regression_linux_m4

The flash_regression_linux_m4 target adds M4 image comparing to the flash target. Take care of thefollowing two parts for this target.
– The -flags 0x00200000 option
This option is the boot flag that is passed to SCFW during boot. The definition of the flags can be found in
sc_fw_port.pdf.
Table 3. Flag definition
Flag

Bit

Meaning

SC_BD_FLAGS_NOT_SECURE

16

Initial boot partition is not secure

SC_BD_FLAGS_NOT_ISOLATED

17

Initial boot partition is not isolated

SC_BD_FLAGS_RESTRICTED

18

Initial boot partition is restricted

SC_BD_FLAGS_GRANT

19

Initial boot partition grants access to the SCFWSC_BD_FLAGS_NOT_COHERENT

20

Initial boot partition is not coherent

SC_BD_FLAGS_ALT_CONFIG

21

Alternate SCFW configuration (passed to board.c)

SC_BD_FLAGS_EARLY_CPU_START

22

Start some CPUs early

SC_BD_FLAGS_DDRTEST

23

Configured for DDR stress test

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

21 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
Table 3. Flag definition...continued
Flag
SC_BD_FLAGS_NO_AP

Bit
24

Meaning
Do not boot AP even if requested by ROM

As shown in Table 3, -flags 0x00200000 means that SC_BD_FLAGS_ALT_CONFIG is set. This flag isused in the board_system_config() function in board.c. SCU creates partition and assigns resources for M4
only when this flag is set.
– The booting address of M4 core
Based on the user requirement, M4 core can boot from internal memory TCM, external memory DRAM, orexternal device like NOR flash. When compiling the M4 image with M4 SDK, there are specific link files foreach method. Users must choose the correct link files according to the boot method they have chosen andalign the booting address here with the address defined in the link files.
– For the flash_regession_linux_m4 target, assume that the boot method is booting from TCM.
Therefore, the booting address is 0x34FE0000.
– For targets ending with m4_ddr, assume that the boot method is booting from DDR and the booting
address is 0x88000000.
– For targets ending with m4_xip, assume that the boot method is booting from QSPI NOR flash and thebooting address is 0x08081000, as shown below.

• flash_linux_m4

The difference between flash_linux_m4 and flash_regession_linux_m4 is that SPL image is added.
For SPL boot, the ROM code only loads SPL image to OCRAM. After SPL image boots from OCRAM, it tries
to read remained image (such as, u-boot-aft-container.img) from boot device and load to DDR. Takecare of the following three parts for this target.
– The u-boot-aft-container.img image
This image is generated from ATF image bl31.bin and U-Boot image u-boot-hash.bin as below. If it
exists in the folder, it also includes TEE image tee.bin.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

22 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board– The -dcd skip option
In non-SPL boot method, the ROM code loads A core booting image from boot device to DRAM, so the
ROM code must initialize DDR before loading. But in SPL boot method, the ROM code only loads SPL
image into OCRAM. Therefore, the DDR initialization can be skipped in ROM code and be done later in
SCFW. The -dcd skip option sets a flag in image container, so when ROM code read the image container, it
knows how it configures.
Note: If the M4 must boot from DDR, ROM code still loads M4 image into DRAM. In such cases, the -dcd
skip is not applicable, as shown below in the flash_linux_m4_ddr target.

For more details about -dcd skip option and DDR initialization flow, see Chapter 4.6 DDR Configuration in
sc_fw_port.pdf.
– The booting address of A core
In SPL boot method, since the ROM code loads SPL image into OCRAM, the booting address of A corealso changes to OCRAM address 0x00100000.
• flash_linux_m4_xip

The main change between the flash_linux_m4_xip and flash_linux_m4 is that M4 is booting fromQSPI NOR FLASH device instead of TCM. Besides the M4 core booting address mentioned above, take careof the QSPI header file.
For flash.bin image to boot from QSPI/FSPI device, the header file is needed in the image for ROM code
to configure QSPI/FSPI device. The sample QSPI/FSPI header file is provided in imx-mkimage/scripts/
fspi_header. To choose QSPI/FSPI device as boot device, modify the header file to fit the devices.
For example, in the sample header file, we can see that the value for offset 0x44-0x47 is 0x01010200.
01010200 /* Serial Nor, Single/Dual/Quad/Octal, SerialClkFreq 1 - 20MHz, 2 50MHz... */To translate this setting, see Chapter 5.8.3.3 FlexSPI configuration parameters in i.MX 8QuadMax
Applications Processor Reference Manual (document IMX8QMRM).
AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

23 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
Table 4. FlexSPI configuration parametersdevicetype

0x044

1

1 - Serial NOR

sflashPadType

0x045

j

1 - Single pad
2 - Dual pads
4 - Quad pads
8 - Octal pads

serialClkFreq

Chip-specific value, for this silicon

1

0x046

1 - 20 MHz
2 - 50 MHz
3 - 62 MHz for SDR and 200 MHz for DDR
4 - 80 MHz
5 - 100 MHz
6 - 133 MHz
7 - 166 MHz for SDR and 200 MHz for DDR
Other values: 20 MHz
IutCustomSeqEnable

0x047

0 - Use predefined LUT sequence index and number

1

1 - Use LUT sequence parameters provided in this block

Here we can see that, in the sample header file,– The value of deviceType is 0x01, which is Serial NOR.
– The value of sflashPadType is 0x1, which is Single pad.
– The value of serialClkFreq is 0x02, which is 50 MHz.
– The value of lutCustomSeqEnable is 0x00, which is Use pre-defined LUT sequence index and number.
For all parameters in the header file, check the definition in Chapter 5.8.3.3 FlexSPI configuration
parameters in i.MX 8QuadMax Applications Processor Reference Manual (document IMX8QMRM) and set
the correct value for the FSPI device.

7.3 Generating flash.bin image
To generate flash.bin image, compile an internal tool, mkimage_imx8, using the gcc in the Linux hostenvironment of the user. The source code of mkimage_imx8 is in imx-mkimage/src.
Since it is automatically compiled when using the following command to generate flash.bin image, there is noneed to compile mkimage_imx8 separately.
The command to generate flash.bin image is:$make SOC=<SOC_TARGET> REV=<SOC_REV> [TARGET]The SOC_TARGET is the target chips, SOC_REV is the reversion of chips, and TARGET is introduced in
Section 7.2.
Note:
For iMX8QXP B0 and C0 chips, the SECO FW is not compatible with each other. Therefore, the REV is used to
specify the version of SECO FW.
• For iMX8QXP B0 chips, use the SECO FW, mx8qxb0-ahab-container.img.
AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

24 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board• For iMX8QXP C0 chips, use the SECO FW, mx8qxc0-ahab-container.img.
Taking our imx8qxp auto board as an example, to build a flash.bin image with M4 image and SPL image,use the command:$make SOC=iMX8QX REV=C0 flash_linux_m4
The flash.bin binary file is generated in imx-mkimage/iMX8QX/flash.bin.

7.4 Burning flash.bin images
For i.MX8/8X chips, the ROM code supports to boot from following boot devices:• SD/MMC• NAND FLASH• FlexSPI NOR flash• Serial downloader support on USB 2.0 OTG and USB 3.0 (as 2.0)
Usually SD card is the most efficient way to verify if the generated flash.bin image can boot the board
successfully.
To burn flash.bin image into SD card, insert the SD card on a Linux host PC. Assuming the SD card isrecognized as /dev/sdx, use the following command to burn flash.bin into SD card:$sudo umount /dev/sdx*$sudo dd if=flash.bin of=/dev/sdx bs=1k seek=32 conv=fsync && sync
For how to burn flash.bin image into other boot device, see Chapter 4.4 Downloading images in i.MX Linux
User's Guide (document IMXLUG).

8 Linux kernel porting
Comparing to previous chapters, users are more familiar to Linux kernel porting. This chapter focuses on the
porting effort for our imx8qxp auto reference board to illustrate the process of adding new device tree file anddrivers for a new customized board.
For Linux file system porting such as adding new user space tools or package, seei.MX_Yocto_Project_User’s_Guide.pdf.

8.1 Creating files for a new board
To create files for a new board, perform the following steps:
1. Add a board defconfig in arch/arm64/configs/.
The defconfig file defines the component that is included in the Linux kernel. In general, each board has a
specific defconfig file according to the hardware design and software requirement.
The imx8qxp auto board, it is similar to the MEK reference board. Therefore, use the default defconfig file inarch/ arm64/configs/imx_v8_defconfig directly as the defconfig file. For other iMX8 customized boards, use
the imx_v8_defconfig as reference and add modification accordingly.
2. Add a board dts in arch/arm64/boot/dts/freescale/.
For the imx8qxp auto board, create the following dts/dtsi files, which are copied from files for MEK board tosave the efforts.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

25 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
Table 5. Device tree files created for auto board in Linux kernel
File location

Descriptionarch/arm64/boot/dts/freescale/imx8qxp-auto.dts

The dts files for auto board without rpmsg, which
includes imx8qxp.dtsi and imx8x-auto.dtsi.

arch/arm64/boot/dts/freescale/imx8qxp-auto-rpmsg.dts

The dts file for auto board with rpmsg, which
includes imx8qxp-auto.dts and imx8x-autorpmsg.dtsi.

arch/arm64/boot/dts/freescale/imx8x-auto.dtsi

The dtsi file for auto board without rpmsg, whichenables the device node that needed.

arch/arm64/boot/dts/freescale/imx8x-auto-rpmsg.dtsi

The dtsi file for auto board with rpmsg, whichenables the device node that needed.

arch/arm64/boot/dts/freescale/imx8qxp-auto-enet-tja1101.dts

The dts file for auto board with TJA1101
Ethernet PHY enabled, which includes imx8qxpauto.dts and imx8qxp- auto-enet-tja1101.dtsi.

arch/arm64/boot/dts/freescale/imx8qxp-auto-enet-tja1101.dtsi

The dtsi file for auto board with TJA1101
Ethernet PHY enabled.

The difference between dts with and without rpmsg is on resources related to M4 core. If M4 core is used,2
assign some of the peripheral interface resources to M4 partition in SCFW as mentioned before, like I C
and FlexCAN. Therefore, disable these resources in dts or use virtual driver like imx_rpmsg_i2c for I2C
interface.
3. Add new drivers for devices on the board.
For an imx8qxp auto board, add the following three hardware components in the board design:• MIPI-CSI with NVP6324 automotive AHD solution• LVDS display with TI DS90UB947/948 SerDes (through FPD-Link III) for automotive application• MIPI-DSI display with Maxim 96752/96755 SerDes (through GMSL2) for automotive application
Table 6 lists the corresponding drivers to be added in the kernel code.
Table 6. Driver files added for auto board in Linux kernel
File location

Description

drivers/gpu/drm/bridge/ds90ub94x.c

Driver of TI DS90UB947/948 SerDes

drivers/gpu/drm/bridge/mx9675x.cDriver of Maxim 96752/96755 SerDes

drivers/media/platform/imx8/nvp6324/

New folder for NVP6324

drivers/media/platform/imx8/nvp6324/Kconfig

Kconfig of NVP6324 driverdrivers/media/platform/imx8/nvp6324/Makefile

Makefile of NVP6324 driverdrivers/media/platform/imx8/nvp6324/nvp6324.h

Header file of NVP6324 driverdrivers/media/platform/imx8/nvp6324/nvp6324_core.cCore function file of NVP6324 driverdrivers/media/platform/imx8/nvp6324/nvp6324_mipi.c

MIPI settings of NVP6324 driverdrivers/media/platform/imx8/nvp6324/nvp6324_video.c

Video mode settings of NVP6324 driverdrivers/media/platform/imx8/nvp6324/nvp6324_video_eq.c

Video event queue settings of NVP6324 driver

8.2 Modifying files for a new board
To modify files for a new board, perform the following steps:

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

26 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
1. Edit related makefiles to be compiled into kernel image. In the imx8qxp auto board example, the related
makefiles include:• arch/arm64/boot/dts/freescale/Makefile
Add dtb files of imx8qxp auto board.

• drivers/gpu/drm/bridge/Makefile
Add ds90ub94x and mx9675x driver.

• drivers/media/platform/imx8/Makefile
Include nvp6324 folder for nvp6324 driver.

2. Modify the dts files according to the board design. For example, on imx8qxp auto board, the connection on
LVDS0 is designed in such method:
ldb1 -> ds90ub947 -> ds90ub948 -> it6263 -> HDMI screen
Therefore, the ldb1 and i2c0_mipi_lvds0 device node in imx8x-auto.dtsi is changed as below.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

27 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

The endpoint matching in the dts represents the connection order.
For other board design changes, the related modification is also added in the dts in a similar method.
3. To add specific features or implementations for the new board, modify some existing drivers.

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

28 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
For example, in the imx8qxp auto board design, to connect an MIPI-DSI panel on Maxim 96755 SerDes,
add the settings of this panel in drivers/gpu/drm/panel/panel-simple.c as below.

8.3 Compiling Linux kernel
To compile Linux kernel, perform the following steps:
1. Set building environment.
The toolchain used to compile Linux kernel is the same cross-compile toolchain used for compiling ATF and
U-Boot. For how to generate and install the toolchain, see Chapter 4.5.12 How to build U-Boot and kernel instandalone environment in i.MX Linux User's Guide (document IMXLUG).
https://www.nxp.com/webapp/Download?colCode=L5.4.47_2.2.0_LINUX_DOCS
2. Compile the code.
To build the Linux kernel for the target board, perform as below:
a. Use the following command to generate configuration file for the board. In this example, the default
defconfig is used for the auto board.
$ make imx_v8_defconfig

AN13275

Application note

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

29 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
b. Use the following command to generate Linux kernel for the target board. The related dtb files are also
generated.
$ make -j8
c. The compiled Linux kernel image is arch/arm64/boot/Image and dtb files are located in arch/arm64/boot/dts/ freescale/ folder.

8.4 Burning Linux kernel• If the SD/MMC is already partitioned into bootpartition and rootfs partition, use the following command tocopy kernel image and dtb files to bootpartition directly.
$sudo mount /dev/sdx1 /mnt/boot/$sudo cp Image /mnt/boot/$sudo cp imx8qxp-auto.dtb /mnt/boot/$sudo umount /dev/sdx1• If the SD/MMC is not partitioned yet, follow the step in Chapter 4.3 Preparing an SD/MMC card to boot ofi.MX Linux User's Guide (document IMXLUG) to partition SD/MMC and then burn kernel image and dtb tobootpartition.

9 Revision history
Table 7 summarizes the revisions to this document.
Table 7. Revision history
Rev.

Date

1

26 May 2023

Updated Section 1.3

0

10 June 2021

Initial release

AN13275

Application note

Substantive changes

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

30 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

10 Legal information
10.1 Definitions
Draft — A draft status on a document indicates that the content is still
under internal review and subject to formal approval, which may resultin modifications or additions. NXP Semiconductors does not give any
representations or warranties as to the accuracy or completeness of
information included in a draft version of a document and shall have noliability for the consequences of use of such information.

Export control — This document as well as the item(s) described herein
may be subject to export control regulations. Export might require a priorauthorization from competent authorities.

10.2 Disclaimers
Limited warranty and liability — Information in this document is believed
to be accurate and reliable. However, NXP Semiconductors does not give
any representations or warranties, expressed or implied, as to the accuracy
or completeness of such information and shall have no liability for theconsequences of use of such information. NXP Semiconductors takes noresponsibility for the content in this document if provided by an information
source outside of NXP Semiconductors.
In no event shall NXP Semiconductors be liable for any indirect, incidental,
punitive, special or consequential damages (including - without limitation lost profits, lost savings, business interruption, costs related to the removalor replacement of any products or rework charges) whether or not suchdamages are based on tort (including negligence), warranty, breach ofcontract or any other legal theory.
Notwithstanding any damages that customer might incur for any reason
whatsoever, NXP Semiconductors’ aggregate and cumulative liability
towards customer for the products described herein shall be limited inaccordance with the Terms and conditions of commercial sale of NXP
Semiconductors.
Right to make changes — NXP Semiconductors reserves the right tomake changes to information published in this document, including without
limitation specifications and product descriptions, at any time and without
notice. This document supersedes and replaces all information supplied prior
to the publication hereof.
Suitability for use — NXP Semiconductors products are not designed,
authorized or warranted to be suitable for use in life support, life-critical orsafety-critical systems or equipment, nor in applications where failure or
malfunction of an NXP Semiconductors product can reasonably be expected
to result in personal injury, death or severe property or environmental
damage. NXP Semiconductors and its suppliers accept no liability forinclusion and/or use of NXP Semiconductors products in such equipment orapplications and therefore such inclusion and/or use is at the customer’s own
risk.
Applications — Applications that are described herein for any of theseproducts are for illustrative purposes only. NXP Semiconductors makes norepresentation or warranty that such applications will be suitable for the
specified use without further testing or modification.
Customers are responsible for the design and operation of theirapplications and products using NXP Semiconductors products, and NXP
Semiconductors accepts no liability for any assistance with applications or
customer product design. It is customer’s sole responsibility to determine
whether the NXP Semiconductors product is suitable and fit for thecustomer’s applications and products planned, as well as for the planned
application and use of customer’s third party customer(s). Customers should
provide appropriate design and operating safeguards to minimize the risks
associated with their applications and products.
NXP Semiconductors does not accept any liability related to any default,
damage, costs or problem which is based on any weakness or default
in the customer’s applications or products, or the application or use bycustomer’s third party customer(s). Customer is responsible for doing allnecessary testing for the customer’s applications and products using NXP
Semiconductors products in order to avoid a default of the applications
and the products or of the application or use by customer’s third party
customer(s). NXP does not accept any liability in this respect.

AN13275

Application noteTerms and conditions of commercial sale — NXP Semiconductors
products are sold subject to the general terms and conditions of commercial
sale, as published at http://www.nxp.com/profile/terms, unless otherwise
agreed in a valid written individual agreement. In case an individual
agreement is concluded only the terms and conditions of the respective
agreement shall apply. NXP Semiconductors hereby expressly objects toapplying the customer’s general terms and conditions with regard to thepurchase of NXP Semiconductors products by customer.

Suitability for use in non-automotive qualified products — Unless
this data sheet expressly states that this specific NXP Semiconductors
product is automotive qualified, the product is not suitable for automotive
use. It is neither qualified nor tested in accordance with automotive testingor application requirements. NXP Semiconductors accepts no liability forinclusion and/or use of non-automotive qualified products in automotive
equipment or applications.
In the event that customer uses the product for design-in and use inautomotive applications to automotive specifications and standards,
customer (a) shall use the product without NXP Semiconductors’ warrantyof the product for such automotive applications, use and specifications, and(b) whenever customer uses the product for automotive applications beyond
NXP Semiconductors’ specifications such use shall be solely at customer’s
own risk, and (c) customer fully indemnifies NXP Semiconductors for any
liability, damages or failed product claims resulting from customer design anduse of the product for automotive applications beyond NXP Semiconductors’
standard warranty and NXP Semiconductors’ product specifications.
Translations — A non-English (translated) version of a document, including
the legal information in that document, is for reference only. The English
version shall prevail in case of any discrepancy between the translated andEnglish versions.
Security — Customer understands that all NXP products may be subject tounidentified vulnerabilities or may support established security standards or
specifications with known limitations. Customer is responsible for the designand operation of its applications and products throughout their lifecycles
to reduce the effect of these vulnerabilities on customer’s applications
and products. Customer’s responsibility also extends to other open and/or
proprietary technologies supported by NXP products for use in customer’s
applications. NXP accepts no liability for any vulnerability. Customer should
regularly check security updates from NXP and follow up appropriately.
Customer shall select products with security features that best meet rules,
regulations, and standards of the intended application and make theultimate design decisions regarding its products and is solely responsible
for compliance with all legal, regulatory, and security related requirements
concerning its products, regardless of any information or support that may beprovided by NXP.
NXP has a Product Security Incident Response Team (PSIRT) (reachable
at PSIRT@nxp.com) that manages the investigation, reporting, and solution
release to security vulnerabilities of NXP products.
NXP B.V. - NXP B.V. is not an operating company and it does not distributeor sell products.

10.3 Trademarks
Notice: All referenced brands, product names, service names, andtrademarks are the property of their respective owners.
NXP — wordmark and logo are trademarks of NXP B.V.

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

31 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board
AMBA, Arm, Arm7, Arm7TDMI, Arm9, Arm11, Artisan, big.LITTLE,
Cordio, CoreLink, CoreSight, Cortex, DesignStart, DynamIQ, Jazelle,
Keil, Mali, Mbed, Mbed Enabled, NEON, POP, RealView, SecurCore,
Socrates, Thumb, TrustZone, ULINK, ULINK2, ULINK-ME, ULINKPLUS, ULINKpro, μVision, Versatile — are trademarks and/or registeredtrademarks of Arm Limited (or its subsidiaries or affiliates) in the US and/or
elsewhere. The related technology may be protected by any or all of patents,
copyrights, designs and trade secrets. All rights reserved.

AN13275

Application note

i.MX — is a trademark of NXP B.V.

All information provided in this document is subject to legal disclaimers.

Rev. 1 — 26 May 2023

© 2023 NXP B.V. All rights reserved.

32 / 33

AN13275

NXP Semiconductors

How to Enable Linux BSP L5.4 on a New i.MX8/8X Board

Contents
1
1.1
1.2
1.3
2
2.1
2.2
3
3.1
3.2
3.3
4
5
5.1
5.2
5.3
6
6.1
6.2
6.3
7
7.1
7.2
7.3
7.4
8
8.1
8.2
8.3
8.4
9
10

Introduction ......................................................... 2
Purpose ..............................................................2
Example board .................................................. 2
Linux BSP releases ........................................... 2
Generating DDR configuration files .................. 3
Downloading RPA tools ..................................... 3
Using RPA tools ................................................ 3
SCFW porting ...................................................... 6
Extracting SCFW code ...................................... 6
Creating a board file ..........................................6
Compiling SCFW ............................................... 9
Running a DDR stress test .............................. 11
ATF porting ........................................................ 13
Power management .........................................13
Resource partitioning .......................................14
Compiling ATF ................................................. 15
U-Boot porting ...................................................16
Creating files for a new board ......................... 16
Modifying files for a new board ........................17
Compiling U-Boot .............................................20
Building flash.bin image .................................. 20
Copying images to mkimage ........................... 20
Checking makefile ........................................... 21
Generating flash.bin image ..............................24
Burning flash.bin images ................................. 25
Linux kernel porting ......................................... 25
Creating files for a new board ......................... 25
Modifying files for a new board ........................26
Compiling Linux kernel .................................... 29
Burning Linux kernel ........................................30
Revision history ................................................ 30
Legal information .............................................. 31

Please be aware that important notices concerning this document and the product(s)described herein, have been included in section 'Legal information'.

© 2023 NXP B.V.

All rights reserved.

For more information, please visit: http://www.nxp.com
Date of release: 26 May 2023
Document identifier: AN13275