summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorTom Rini <trini@konsulko.com>2019-07-27 09:35:05 -0400
committerTom Rini <trini@konsulko.com>2019-07-27 09:35:05 -0400
commitdf9a7a195bdf0722399199bf373afc8309ae3ad7 (patch)
tree5bf1e2e3388725131640aac7d120647820ca5b48 /doc
parent222701e157176a66628e4f399f52ca3307b018c9 (diff)
parent4a6f5b4f56b8bc6f36736fc0a07c5c4f9069e69b (diff)
downloadu-boot-df9a7a195bdf0722399199bf373afc8309ae3ad7.tar.gz
Merge tag 'u-boot-imx-20190719' of https://gitlab.denx.de/u-boot/custodians/u-boot-imx
u-boot-imx-20190719 - CCF for i.MX6 - nandbcb command to write SPL into NAND - Switch to DM (i.MX28) - Boards: Toradex, engicam, DH - Fixes for i.MX8 - Fixes for i.MX7ULP Travis: https://travis-ci.org/sbabic/u-boot-imx/builds/561147504
Diffstat (limited to 'doc')
-rw-r--r--doc/README.falcon2
-rw-r--r--doc/imx/clk/ccf.txt101
-rw-r--r--doc/imx/common/imx6.txt74
3 files changed, 177 insertions, 0 deletions
diff --git a/doc/README.falcon b/doc/README.falcon
index 9a7f0bc235..713d7063a1 100644
--- a/doc/README.falcon
+++ b/doc/README.falcon
@@ -67,6 +67,8 @@ CONFIG_SYS_NAND_SPL_KERNEL_OFFS Offset in NAND where the kernel is stored
CONFIG_CMD_SPL_NAND_OFS Offset in NAND where the parameters area was saved.
+CONFIG_CMD_SPL_NOR_OFS Offset in NOR where the parameters area was saved.
+
CONFIG_CMD_SPL_WRITE_SIZE Size of the parameters area to be copied
CONFIG_SPL_OS_BOOT Activate Falcon Mode.
diff --git a/doc/imx/clk/ccf.txt b/doc/imx/clk/ccf.txt
new file mode 100644
index 0000000000..36b60dc438
--- /dev/null
+++ b/doc/imx/clk/ccf.txt
@@ -0,0 +1,101 @@
+Introduction:
+=============
+
+This documentation entry describes the Common Clock Framework [CCF]
+port from Linux kernel (v5.1.12) to U-Boot.
+
+This code is supposed to bring CCF to IMX based devices (imx6q, imx7
+imx8). Moreover, it also provides some common clock code, which would
+allow easy porting of CCF Linux code to other platforms.
+
+Design decisions:
+=================
+
+* U-Boot's driver model [DM] for clk differs from Linux CCF. The most
+ notably difference is the lack of support for hierarchical clocks and
+ "clock as a manager driver" (single clock DTS node acts as a starting
+ point for all other clocks).
+
+* The clk_get_rate() caches the previously read data if CLK_GET_RATE_NOCACHE
+ is not set (no need for recursive access).
+
+* On purpose the "manager" clk driver (clk-imx6q.c) is not using large
+ table to store pointers to clocks - e.g. clk[IMX6QDL_CLK_USDHC2_SEL] = ....
+ Instead we use udevice's linked list for the same class (UCLASS_CLK).
+
+ Rationale:
+ ----------
+ When porting the code as is from Linux, one would need ~1KiB of RAM to
+ store it. This is way too much if we do plan to use this driver in SPL.
+
+* The "central" structure of this patch series is struct udevice and its
+ uclass_priv field contains the struct clk pointer (to the originally created
+ one).
+
+* Up till now U-Boot's driver model (DM) CLK operates on udevice (main
+ access to clock is by udevice ops)
+ In the CCF the access to struct clk (embodying pointer to *dev) is
+ possible via dev_get_clk_ptr() (it is a wrapper on dev_get_uclass_priv()).
+
+* To keep things simple the struct udevice's uclass_priv pointer is used to
+ store back pointer to corresponding struct clk. However, it is possible to
+ modify clk-uclass.c file and add there struct uc_clk_priv, which would have
+ clock related members (like pointer to clk). As of this writing there is no
+ such need, so to avoid extra allocations (as it can be auto allocated by
+ setting .per_device_auto_alloc_size = sizeof(struct uc_clk_priv)) the
+ uclass_priv stores the pointer to struct clk.
+
+* It is advised to add common clock code (like already added rate and flags) to
+ the struct clk, which is a top level description of the clock.
+
+* U-Boot's driver model already provides the facility to automatically allocate
+ (via private_alloc_size) device private data (accessible via dev->priv).
+ It may look appealing to use this feature to allocate private structures for
+ CCF clk devices e.g. divider (struct clk_divider *divider) for IMX6Q clock.
+
+ The above feature had not been used for following reasons:
+ - The original CCF Linux kernel driver is the "manager" for clocks - it
+ decides when clock is instantiated (and when memory for it is allocated).
+
+ - Using it would change the original structure of the CCF code.
+
+ - To bind (via clk_register()) the clock device with U-Boot driver model we
+ first need udevice for it (the "chicken and egg problem").
+
+* I've added the clk_get_parent(), which reads parent's dev->uclass_priv to
+ provide parent's struct clk pointer. This seems the easiest way to get
+ child/parent relationship for struct clk in U-Boot's udevice based clocks.
+
+* Linux's CCF 'struct clk_core' corresponds to U-Boot's udevice in 'struct clk'.
+ Clock IP block agnostic flags from 'struct clk_core' (e.g. NOCACHE) have been
+ moved from this struct one level up to 'struct clk'.
+
+* For tests the new ./test/dm/clk_ccf.c and ./drivers/clk/clk_sandbox_ccf.c
+ files have been introduced. The latter setups the CCF clock structure for
+ sandbox by reusing, if possible, generic clock primitives - like divier
+ and mux. The former file provides code to tests this setup.
+
+ For sandbox new CONFIG_SANDBOX_CLK_CCF Kconfig define has been introduced.
+ All new primitives added for new architectures must have corresponding test
+ in the two aforementioned files.
+
+
+Testing (sandbox):
+==================
+
+make mrproper; make sandbox_defconfig; make -j4
+./u-boot -i -d arch/sandbox/dts/test.dtb
+=> ut dm clk
+
+or in a more "scriptable" way (with -v to print debug output):
+./u-boot --fdt arch/sandbox/dts/test.dtb --command "ut dm clk_ccf" -v
+
+To do:
+------
+
+* Use of OF_PLATDATA in the SPL setup for CCF - as it is now - the SPL grows
+ considerably and using CCF in boards with tiny resources (OCRAM) is
+ problematic.
+
+* On demand port other parts of CCF to U-Boot - as now only features _really_
+ needed by DM/DTS converted drivers are used.
diff --git a/doc/imx/common/imx6.txt b/doc/imx/common/imx6.txt
index eab88353f6..0b5061128c 100644
--- a/doc/imx/common/imx6.txt
+++ b/doc/imx/common/imx6.txt
@@ -88,3 +88,77 @@ Reading bank 4:
Word 0x00000002: 9f027772 00000004
+NAND Boot on i.MX6 with SPL support
+--------------------------------------
+
+Writing/updating boot image in nand device is not straight forward in
+i.MX6 platform and it requires boot control block(BCB) to be configured.
+
+BCB contains two data structures, Firmware Configuration Block(FCB) and
+Discovered Bad Block Table(DBBT). FCB has nand timings, DBBT search area,
+and firmware. See IMX6DQRM Section 8.5.2.2
+for more information.
+
+We can't use 'nand write' command to write SPL/firmware image directly
+like other platforms does. So we need special setup to write BCB block
+as per IMX6QDL reference manual 'nandbcb update' command do that job.
+
+for nand boot, up on reset bootrom look for FCB structure in
+first block's if FCB found the nand timings are loaded for
+further reads. once FCB read done, DTTB will be loaded and
+finally firmware will be loaded which is boot image.
+
+cmd_nandbcb will create FCB these structures
+by taking mtd partition as an example.
+- initial code will erase entire partition
+- followed by FCB setup, like first 2 blocks for FCB/DBBT write,
+ and next block for FW1/SPL
+- write firmware at FW1 block and
+- finally write fcb/dttb in first 2 block.
+
+Typical NAND BCB layout:
+=======================
+
+ no.of blocks = partition size / erasesize
+ no.of fcb/dbbt blocks = 2
+ FW1 offset = no.of fcb/dbbt
+
+block 0 1 2
+ -------------------------------
+ |FCB/DBBT 0|FCB/DBBT 1| FW 1 |
+ --------------------------------
+
+On summary, nandbcb update will
+- erase the entire partition
+- create BCB by creating 2 FCB/BDDT block followed by
+ 1 FW blocks based on partition size and erasesize.
+- fill FCB/DBBT structures
+- write FW/SPL in FW1
+- write FCB/DBBT in first 2 blocks
+
+step-1: write SPL
+
+icorem6qdl> ext4load mmc 0:1 $loadaddr SPL
+39936 bytes read in 10 ms (3.8 MiB/s)
+
+icorem6qdl> nandbcb update $loadaddr spl $filesize
+device 0 offset 0x0, size 0x9c00
+Erasing at 0x1c0000 -- 100% complete.
+NAND fw write: 0x80000 offset, 0xb000 bytes written: OK
+
+step-2: write u-boot-dtb.img
+
+icorem6qdl> nand erase.part uboot
+
+NAND erase.part: device 0 offset 0x200000, size 0x200000
+Erasing at 0x3c0000 -- 100% complete.
+OK
+
+icorem6qdl> ext4load mmc 0:1 $loadaddr u-boot-dtb.img
+589094 bytes read in 37 ms (15.2 MiB/s)
+
+icorem6qdl> nand write ${loadaddr} uboot ${filesize}
+
+NAND write: device 0 offset 0x200000, size 0x8fd26
+ 589094 bytes written: OK
+icorem6qdl>