Documentation/arch/arm/zte/zx297520v3.rst

Source file repositories/reference/linux-study-clean/Documentation/arch/arm/zte/zx297520v3.rst

File Facts

System
Linux kernel
Corpus path
Documentation/arch/arm/zte/zx297520v3.rst
Extension
.rst
Size
6358 bytes
Lines
167
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0-only

====================================
Booting Linux on ZTE zx297520v3 SoCs
====================================

Author:	Stefan Dösinger

Date  : 27 Jan 2026

1. Hardware description
---------------------------
Zx297520v3 SoCs use a 64-bit capable Cortex-A53 CPU and GICv3, although they
run in arm32 mode only. The CPU has support EL3, but no hypervisor (EL2) and
it seems to lack VFP and NEON.

The SoC is used in a number of cheap LTE to WiFi routers, both battery powered
MiFis and stationary CPEs. In addition to the CPU these devices usually have
64 MB Ram (although some is shared with the LTE chip), 128 MB NAND flash, an
SDIO connected RTL8192-type Wifi chip limited to 2.4 ghz operation, USB 2,
and buttons. Devices with as low as 32 MB or as high as 128 MB ram exist, as
do devices with 8 or 16 MB of NOR flash.

Some devices, especially the stationary ones, have 100 mbit Ethernet and an
Ethernet switch.

Usually the devices have LEDs for status indication, although some have SPI or
I2C connected displays.

Some have an SD card slot. If it exists, it is a better choice for the root
file system because it easily outperforms the built-in NAND.

The LTE interface runs on a separate DSP called ZSP880. It is probably derived
from LSI ZSPs and has an undocumented instruction set. The ZSP communicates
with the main CPU via SRAM and DRAM and a mailbox hardware that can generate
IRQs on either ends.

There is also a Cortex M0 CPU, which is responsible for early HW initialization
and starting the Cortex A53 CPU. It does not have any essential purpose once
U-Boot is started. An SRAM-based handover protocol exists to run custom code on
this CPU.

2. Booting via USB
---------------------------

The Boot ROM has support for booting custom code via USB. This mode can be
entered by connecting a Boot PIN to GND or by modifying the third byte on NAND
(set it to anything other than 0x5A aka 'Z'). A free software tool to start
custom U-Boot and kernels can be found here:

https://github.com/zx297520v3-mainline/zx297520v3-loader

If USB download mode is entered but no boot commands are sent through USB, the
device will proceed to boot normally after a few seconds. It is therefore
possible to enable USB boot permanently and still leave the default boot files
in place.

https://github.com/zx297520v3-mainline/u-boot-mainline

Contains an U-Boot version that can be used with the USB loader and sets up the
CPU and interrupt controller to comply with Linux's booting requirements.

3. Building for built-in U-Boot
-------------------------------
The devices come with an ancient U-Boot that loads legacy uImages from NAND and
boots them without a chance for the user to interrupt. The images are stored in
files ap_cpuap.bin and ap_recovery.bin on a jffs2 partition named imagefs,
usually mtd4. A file named "fotaflag" switches between the two modes.

In addition to the uImage header, those files have a 384-byte signature header,

Annotation

Implementation Notes