1.. SPDX-License-Identifier: GPL-2.0+
2
3Pre-Generated FIP File Repo
4===========================
5
6Pre-built Flattened Image Package (FIP) sources and Amlogic signing binaries for many
7commercially available boards and some Android STB devices are collected for use with
8distro build-systems here: https://github.com/LibreELEC/amlogic-boot-fip
9
10Using the pre-built FIP sources to sign U-Boot is simple, e.g. for LePotato:
11
12.. code-block:: bash
13
14    $ git clone https://github.com/LibreELEC/amlogic-boot-fip --depth=1
15    $ cd amlogic-boot-fip
16    $ mkdir my-output-dir
17    $ ./build-fip.sh lepotato /path/to/u-boot/u-boot.bin my-output-dir
18
19Then write U-Boot to SD or eMMC with:
20
21.. code-block:: bash
22
23    $ DEV=/dev/boot_device
24    $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=512 skip=1 seek=1
25    $ dd if=fip/u-boot.bin.sd.bin of=$DEV conv=fsync,notrunc bs=1 count=440
26
27Files Included
28--------------
29
30Amlogic ARMv8 SoCs use a vendor modified variant of the ARM Trusted Firmware-A boot
31architecture. See documentation here: https://www.trustedfirmware.org/projects/tf-a/
32
33Trusted Firmware-A uses the following boot elements (simplified):
34
35- BL1: First boot step implemented in ROM on Amlogic SoCs
36
37- BL2: Second boot step used to initialize the SoC main clocks & DDR interface. BL21
38  and ACS board-specific binaries must be "inserted" into the BL2 binary before signing
39  and packaging in order to be flashed on the platform
40
41- BL30: Amlogic Secure Co-Processor (SCP) firmware used to handle all system management
42  operations (DVFS, suspend/resume, ..)
43
44- BL301: Amlogic Secure Co-Processor (SCP) board-specific firmware "plug-in" to handle
45  custom DVFS & suspend-resume parameters
46
47- BL31: Initializes the interrupt controller and the system management interface (PSCI)
48
49- BL32 (Optional): Is the Trusted Environment Execution (TEE) Operating System used to
50  run secure Trusted Apps, e.g. OP-TEE
51
52- BL33: Is the last non-secure step, usually U-Boot which loads Linux
53
54Amlogic sources provide the following binaries:
55
56- bl2.bin
57- bl30.bin
58- bl30.bin
59- bl31.img
60- bl32.bin
61
62For G12A/B and SM1 Amlogic also provides DDR drivers used by the BL2 binary:
63
64- ddr4_1d.fw
65- ddr4_2d.fw
66- ddr3_1d.fw
67- piei.fw
68- lpddr4_1d.fw
69- lpddr4_2d.fw
70- diag_lpddr4.fw
71- aml_ddr.fw
72
73The following files are generated from the Amlogic U-Boot fork:
74
75- acs.bin: Contains the PLL & DDR parameters for the board
76- bl301.bin: Contains the DVFS & suspend-resume handling code for the board
77- bl33.bin: U-boot binary image
78
79The acs.bin and bl301.bin files use U-Boot GPL-2.0+ headers and U-Boot build system and
80are thus considered to be issued from GPL-2.0+ source code.
81
82Amlogic alo provides pre-compiled x86_64 and Python2 binaries:
83
84- aml_encrypt_gxb
85- aml_encrypt_gxl
86- aml_encrypt_g12a
87- aml_encrypt_g12b
88- acs_tool.pyc
89
90The repo replaces the pre-compiled acs_tool.pyc with a Python3 acs_tool.py that can be
91used with modern build hosts.
92
93The repo also provides the following files used with GXBB boards:
94
95- bl1.bin.hardkernel
96- aml_chksum
97
98The repo also supports the open-source 'gxlimg' signing tool that can be used to sign
99U-Boot binaries for GXL/GXM/G12A/G12B/SM1 boards: https://github.com/repk/gxlimg
100
101Licensing
102---------
103
104The licence of Amlogic provided binaries was not historically clear but has now been
105clarified. The current Amlogic distribution licence is below:
106
107.. code-block:: C
108
109    // Copyright (C) 2018 Amlogic, Inc. All rights reserved.
110    //
111    // All information contained herein is Amlogic confidential.
112    //
113    // This software is provided to you pursuant to Software License
114    // Agreement (SLA) with Amlogic Inc ("Amlogic"). This software may be
115    // used only in accordance with the terms of this agreement.
116    //
117    // Redistribution and use in source and binary forms, with or without
118    // modification is strictly prohibited without prior written permission
119    // from Amlogic.
120    //
121    // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
122    // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
123    // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
124    // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
125    // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
126    // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
127    // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
128    // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
129    // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
130    // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
131    // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
132