[PATCH RFC 9/9] doc: board: amlogic: add u-boot-spl documentation

[Heinrich Schuchardt]

On 9/10/25 09:03, Neil Armstrong wrote:
> On 07/09/2025 16:36, Ferass El Hafidi wrote:
>> Add building and usage instructions for SPL.
>>
>> Signed-off-by: Ferass El Hafidi <funderscore at postmarketos.org>
>> ---
>>   doc/board/amlogic/index.rst             |  1 +
>>   doc/board/amlogic/pre-generated-fip.rst |  9 ++++
>>   doc/board/amlogic/spl.rst               | 77 +++++++++++++++++++++++ 
>> ++++++++++
>>   3 files changed, 87 insertions(+)
>>
>> diff --git a/doc/board/amlogic/index.rst b/doc/board/amlogic/index.rst
>> index 
>> dcd935224ac0280a77455e3475a610fd81cfb80d..23380ac33f2b06efff7d4741ce2967d75671ca13 100644
>> --- a/doc/board/amlogic/index.rst
>> +++ b/doc/board/amlogic/index.rst
>> @@ -78,6 +78,7 @@ Boot Documentation
>>      boot-flow
>>      pre-generated-fip
>> +   spl
>>   Board Documentation
>>   -------------------
>> diff --git a/doc/board/amlogic/pre-generated-fip.rst b/doc/board/ 
>> amlogic/pre-generated-fip.rst
>> index 
>> 6a43d776d43f35cbffc7ba9e72bf05dd719f6387..d820bd09115952d4fca2b9e7d7b5a9e30bd11430 100644
>> --- a/doc/board/amlogic/pre-generated-fip.rst
>> +++ b/doc/board/amlogic/pre-generated-fip.rst
>> @@ -98,6 +98,13 @@ The repo also provides the following files used 
>> with GXBB boards:
>>   The repo also supports the open-source 'gxlimg' signing tool that 
>> can be used to sign
>>   U-Boot binaries for GXL/GXM/G12A/G12B/SM1 boards: https:// 
>> github.com/repk/gxlimg
>> +The following binaries can be replaced with open-source implementations:
>> +
>> +- bl2.bin (GXBB and GXL only)
>> +- bl31.img (GXBB, GXL, AXG and G12A only)
>> +
>> +Refer to `Experimental U-Boot SPL Support`_ if you wish to replace them.
>> +
>>   Licensing
>>   ---------
>> @@ -129,3 +136,5 @@ clarified. The current Amlogic distribution 
>> licence is below:
>>       // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
>> OR TORT
>>       // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 
>> THE USE
>>       // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 
>> DAMAGE.
>> +
>> +.. _`Experimental U-Boot SPL Support`: spl.rst
>> diff --git a/doc/board/amlogic/spl.rst b/doc/board/amlogic/spl.rst
>> new file mode 100644
>> index 
>> 0000000000000000000000000000000000000000..39d50e3da87d71f62cec1903c441c334bf7020e8
>> --- /dev/null
>> +++ b/doc/board/amlogic/spl.rst
>> @@ -0,0 +1,77 @@
>> +.. SPDX-License-Identifier: GPL-2.0+
>> +
>> +Experimental U-Boot SPL Support
>> +===============================
>> +
>> +There's some experimental support for some Amlogic SoCs, in U-Boot 
>> SPL.  It
>> +replaces the proprietary bl2.bin blob used for DRAM init.  Currently 
>> Meson GX
>> +SoCs (GXBB, GXL) are supported.
>> +
>> +A subset of Amlogic boards have SPL enabled.  These boards have been 
>> tested and
>> +known to work to an extent.

%s/known/are known/

>> +
>> +
>> +Building Arm Trusted Firmware (TF-A)
>> +------------------------------------
>> +
>> +This U-Boot SPL port requires the BL31 stage of mainline Arm Trusted
>> +Firmware-A firmware. It provides an open source implementation of secure
>> +software for Armv8-A. Build it with:
>> +
>> +.. code-block:: bash
>> +
>> +    $ git clone https://git.trustedfirmware.org/TF-A/trusted- 
>> firmware-a.git
>> +    $ cd trusted-firmware-a
>> +    $ make CROSS_COMPILE=aarch64-linux-gnu- PLAT=your_soc DEBUG=1
>> +
>> +Replace ``your_soc`` with the SoC target you wish to build for. For 
>> GXBB it's
>> +``gxbb`` and for GXL it's ``gxl``.
>> +
>> +
>> +Building a bl30_new.bin binary
>> +------------------------------
>> +
>> +``bl30_new.bin`` has both ``bl30.bin`` and ``bl301.bin`` binary blobs
>> +bundled. The former is the proper system control processor firmware 
>> and the
>> +latter is a "plug-in" for board-specific DVFS/suspend-resume 
>> parameters. For
>> +more info you may wish to read this page: `Pre-Generated FIP File 
>> Repo`_.
>> +
>> +To build using the FIP file repo, simply issue the following commands:
>> +
>> +.. code-block:: bash
>> +
>> +    $ cd amlogic-boot-fip/your_board

Where do you get this source tree from? It is not contained in TF-A.

Best regards

Heinrich

>> +    $ make bl30_new.bin
>> +
>> +
>> +.. _`Pre-Generated FIP File Repo`: pre-generated-fip.rst
>> +
>> +
>> +U-Boot compilation
>> +------------------
>> +
>> +U-Boot SPL is not enabled by default, instead there are config 
>> fragments that
>> +can be used to enable it, with per-board configuration:
>> +
>> +- ``spl-libretech-cc-1gb.config``: 1 GB LePotato board
>> +- ``spl-libretech-cc-2gb.config``: 2 GB LePotato board
>> +- ``spl-odroid-c2.config``: ODROID-C2
>> +- ``spl-videostrong-kii-pro.config``: Videostrong KII Pro
>> +
>> +Pick one of them then:
>> +
>> +.. code-block:: bash
>> +
>> +    $ export CROSS_COMPILE=aarch64-linux-gnu-
>> +    $ export BL31=path/to/tf-a/bl31.bin                 # Upstream 
>> TF-A BL31 binary
>> +    $ export SCP=path/to/bl30_new.bin                   # 
>> bl30_new.bin binary
>> +    $ make <yourboardname>_defconfig spl-<yourboardname>.config
>> +    $ make
>> +
>> +Write to SD:
>> +
>> +.. code-block:: bash
>> +
>> +    $ DEV=/dev/boot_device
>> +    $ dd if=u-boot-meson-with-spl.bin of=$DEV conv=fsync,notrunc 
>> bs=512 seek=1
>> +
>>
> 
> It's very nice :-)
> 
> Reviewed-by: Neil Armstrong <neil.armstrong at linaro.org>