236 lines
9.6 KiB
Plaintext
236 lines
9.6 KiB
Plaintext
Copyright (c) 2012-2014, The Linux Foundation. All rights reserved.
|
|
|
|
Redistribution and use in source form and compiled forms (SGML, HTML,
|
|
PDF, PostScript, RTF and so forth) with or without modification, are
|
|
permitted provided that the following conditions are met:
|
|
|
|
Redistributions in source form must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer as the
|
|
first lines of this file unmodified.
|
|
|
|
Redistributions in compiled form (transformed to other DTDs,
|
|
converted to PDF, PostScript, RTF and other formats) must reproduce
|
|
the above copyright notice, this list of conditions and the following
|
|
disclaimer in the documentation and/or other materials provided with
|
|
the distribution.
|
|
|
|
THIS DOCUMENTATION IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
|
|
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
|
|
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AND
|
|
NON-INFRINGEMENT ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD
|
|
DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
|
|
DAMAGE.
|
|
|
|
|
|
Android - Table of Device Tree
|
|
==============================
|
|
|
|
0) Document revision
|
|
v1.0 - Initial version (dng)
|
|
v1.1 - Add v2 format to allow subtype (dng)
|
|
|
|
1) Android boot image:
|
|
----------------------
|
|
1.1) Header:
|
|
1) Magic (8B)
|
|
2) kernel size (4B)
|
|
3) kernel addr (4B)
|
|
4) ramdisk size (4B)
|
|
5) ramdisk addr (4B)
|
|
6) 2ndary size (4B)
|
|
7) 2ndary addr (4B)
|
|
8) tags addr (4B)
|
|
9) page size (4B)
|
|
10) unused #1 (4B) (zero in standard Android)
|
|
11) unused #2 (4B) (zero in standard Android)
|
|
12) product name (16B)
|
|
13) kernel cmdline (512B)
|
|
14) id (8B)
|
|
|
|
1.2) Layout:
|
|
A) header (as above - 1 page)
|
|
B) kernel (n pages)
|
|
C) ramdisk (m pages)
|
|
D) second stage (o pages)
|
|
|
|
2) QC table of device tree
|
|
--------------------------
|
|
2.1) Changes:
|
|
i) use "unused #1, #2" members in existing boot image
|
|
header to point to new table of device tree
|
|
(#1 - size of QC table of DT)
|
|
ii) append table of device tree (described later)
|
|
after "D) second stage"
|
|
|
|
2.2) Format:
|
|
size
|
|
x +------------------+
|
|
| | MAGIC ("QCDT") | 4B
|
|
| +------------------+
|
|
header | VERSION | uint32 (version 3)
|
|
| +------------------+
|
|
| | num of DTBs | uint32 (number of DTB entries)
|
|
x +------------------+
|
|
| | platform id #1 | uint32 (e.g. ID for MSM8974)
|
|
| +------------------+
|
|
| | variant id #1 | uint32 (e.g. ID for CDP, MTP)
|
|
| +------------------+
|
|
| | subtype id #1 | uint32 (e.g. ID for subtype) (QCDT v2)
|
|
device +------------------+
|
|
#1 | soc rev #1 | uint32 (e.g. MSM8974 v2)
|
|
entry +------------------+
|
|
| | pmic0 #1 | uint32 (pmic0-> first smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | pmic1 #1 | uint32 (pmic1-> secondary smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | pmic2 #1 | uint32 (pmic2-> third smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | pmic3 #1 | uint32 (pmic3-> fourth smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | offset #1 | uint32 (byte offset from start/before MAGIC
|
|
| +------------------+ to DTB entry)
|
|
| | size #1 | uint32 (size in bytes of DTB blob)
|
|
x +------------------+
|
|
. .
|
|
. . (repeat)
|
|
. .
|
|
|
|
x +------------------+
|
|
| | platform id #Z | uint32 (e.g. ID for MSM8974)
|
|
| +------------------+
|
|
device | variant id #Z | uint32 (e.g. ID for CDP, MTP)
|
|
#Z +------------------+
|
|
entry | subtype id #Z | uint32 (e.g. ID for subtype) (QCDT v2)
|
|
(last) +------------------+
|
|
| | soc rev #Z | uint32 (e.g. MSM8974 v2)
|
|
| +------------------+
|
|
| | pmic0 #1 | uint32 (pmic0-> first smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | pmic1 #1 | uint32 (pmic1-> secondary smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | pmic2 #1 | uint32 (pmic2-> third smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | pmic3 #1 | uint32 (pmic3-> fourth smallest SID of existing pmic)
|
|
| +------------------+
|
|
| | offset #Z | uint32 (byte offset from start/before MAGIC
|
|
x +------------------+ to DTB entry)
|
|
| 0 ("zero") | uint32 (end of list delimiter)
|
|
+------------------+ to DTB entry)
|
|
| padding | variable length for next DTB to start on
|
|
+------------------+ page boundary
|
|
| DTB #1 | variable (start is page aligned)
|
|
| |
|
|
| |
|
|
+------------------+
|
|
| padding | variable length for next DTB to start on
|
|
+------------------+ page boundary
|
|
.
|
|
.
|
|
.
|
|
|
|
+------------------+
|
|
| DTB #Z (last) | variable (start is page aligned)
|
|
| |
|
|
| |
|
|
+------------------+
|
|
|
|
3) Operations
|
|
-------------
|
|
3.1) Build-time:
|
|
1) Each DTS per device will add a "qcom,msm-id" entry
|
|
e.g. for msm8974-sim.dts, add
|
|
qcom,msm-id = <x y z>;
|
|
or
|
|
qcom,msm-id = <x z>;
|
|
qcom,board-id = <y y'>;
|
|
or
|
|
qcom,msm-id = <x z>;
|
|
qcom,board-id = <y y'>;
|
|
qcom,pmic-id = <a b c d>;
|
|
x = ID for msm8974
|
|
y = ID for CDP, MTP, etc.
|
|
y' = ID for subtype (assumed zero if absent)
|
|
z = ID for soc revision
|
|
a = pmic0
|
|
b = pmic1
|
|
c = pmic2
|
|
d = pmic3
|
|
SBL populates the pmic entries always in ascending order of SID, so
|
|
pmic0-> SID0, pmic1-> SID1, pmic2-> SID2, pmic3-> SID3.
|
|
e.g. for qcom,pmic-id = <pmic0 pmic1 pmic2 pmic3>
|
|
Board X = MSM8994 + PM8994 + PMI8994 (Existing boards [ROW])
|
|
Board Y = MSM8994 + PM8994 + PMI8994 + PM8004 (Internal SS board variant)
|
|
Board Z = MSM8994 + PM8994 + PM8004 (Boards that SS will be making)
|
|
|
|
For all boards X, Y, and Z, PMICs have the following SIDs and REVID SUBTYPEs
|
|
(i.e. PMIC Model):
|
|
PM8994 - SID 0 and 1; subtype = 9
|
|
PMI8994 - SID 2 and 3; subtype = 10
|
|
PM8004 - SID 4 and 5; subtype = 12
|
|
|
|
LK using SMEM PMIC info(1 as major and 0 as minor version for example):
|
|
Board X: qcom,pmic-id = <0x0109 0x010A 0x0 0x0>;
|
|
Board Y: qcom,pmic-id = <0x0109 0x010A 0x010C 0x0>;
|
|
Board Z: qcom,pmic-id = <0x0109 0x010C 0x0 0x0>;
|
|
|
|
The entry can optionally be an array:
|
|
qcom,msm-id = <x1 y1 z1>, <x2 y2 z2>, ...;
|
|
or
|
|
qcom,msm-id = <x1 z1>, <x2 z2>, ...;
|
|
qcom,board-id = <y1 y1'>, ...;
|
|
or
|
|
qcom,msm-id = <x1 z1>, <x2 z2>, ...;
|
|
qcom,board-id = <y1 y1'>, ...;
|
|
qcom,pmic-id = <a1 b1 c1 d1>, ...;
|
|
Note that qcom,msm-id, qcom,board-id and qcom,pmic-id are not matched pairs.
|
|
2) Kernel compile will generate the DTB
|
|
3) Android build will run a new tool (dtbTool)
|
|
a) scan the DTB output directory for all compiled DTB
|
|
b) decompile the DTB for "qcom,msm-id"/"qcom,board-id"/"qcom,pmic-id"
|
|
c) generate the QC table of device tree in sorted
|
|
order (platform, variant, subtype, soc rev, pmic0, pmic1, pmic2, pmic3)
|
|
d) modified mkbootimg will merge new table of DT
|
|
|
|
3.2) Run-time:
|
|
1) LK bootloader will obtain platform id/variant/subtype/soc rev/major ver/minor ver
|
|
/pmic0/pmic1/pmic2/pmic3 info either from early bootloaders or via other means
|
|
2) LK bootloader will check entries #10 for non-zero
|
|
value (set to zero for standard boot.img). If the
|
|
value is non-zero, refer to page section after
|
|
the "second stage" in the boot.img layout
|
|
3) Check QCDT magic
|
|
4) Check QCDT version (optional LK to handle multiple
|
|
QCDT version)
|
|
5) LK scans through the QCDT table to look for matching
|
|
entry. Search order is:
|
|
1) msm ID exact match
|
|
2) Platform type exact match
|
|
3) subtype ID exact match
|
|
4) HLOS subtype exact match
|
|
5) Pmic0 model ID exact match
|
|
6) Pmic1 model ID exact match
|
|
7) Pmic2 model ID exact match
|
|
8) Pmic3 model ID exact match
|
|
9) foundry ID, look for exact match, if not found choose
|
|
device tree with foundry-id(0x0)
|
|
10) select the highest soc rev in QCDT that is
|
|
equal to or lower than the runtime detected soc rev
|
|
11) select the highest major&minor ver in QCDT that is
|
|
equal to or lower than the runtime detected major ver
|
|
12) select the highest pmic0 major&minor in QCDT that is
|
|
equal to or lower than the runtime detected pmic0
|
|
13) select the highest pmic1 major&minor in QCDT that is
|
|
equal to or lower than the runtime detected pmic1
|
|
14) select the highest pmic2 major&minor in QCDT that is
|
|
equal to or lower than the runtime detected pmic2
|
|
15) select the highest pmic3 major&minor in QCDT that is
|
|
equal to or lower than the runtime detected pmic3
|
|
6) Load the matching DTB blob to the tags addr
|
|
7) LK pass the correct DTB to the kernel
|