-
Notifications
You must be signed in to change notification settings - Fork 0
/
mainline-head.rst
1512 lines (1037 loc) · 50.8 KB
/
mainline-head.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.. Download links
.. |dlpage-bsp| replace:: our BSP
.. _dlpage-bsp: https://www.phytec.de/bsp-download/?bsp=BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.1
.. |dlpage-product| replace:: https://www.phytec.de/produkte/system-on-modules/phycore-imx-8m-plus/#downloads
.. _dl-server: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MP/
.. |link-image| replace:: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MP/BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.1/images/ampliphy-xwayland/phyboard-pollux-imx8mp-3/phytec-qt6demo-image-phyboard-pollux-imx8mp-3.rootfs.wic
.. |link-partup-package| replace:: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MP/BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.1/images/ampliphy-xwayland/phyboard-pollux-imx8mp-3/phytec-qt6demo-image-phyboard-pollux-imx8mp-3.rootfs.partup
.. |link-boot-tools| replace:: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MP/BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.1/images/ampliphy-xwayland/phyboard-pollux-imx8mp-3/
.. _releasenotes: https://git.phytec.de/phy2octo/tree/releasenotes?h=imx8mp
.. General Substitutions
.. |doc-id| replace:: L-XXXXX.Xx
.. |kit| replace:: **phyCORE-i.MX8M Plus Kit**
.. |kit-ram-size| replace:: 2GiB
.. |sbc| replace:: phyBOARD-Pollux
.. |soc| replace:: i.MX 8M Plus
.. |socfamily| replace:: i.MX 8
.. |som| replace:: phyCORE-i.MX8MP
.. |debug-uart| replace:: ttymxc0
.. |serial-uart| replace:: ttymxc1
.. |expansion-connector| replace:: X6
.. Linux Kernel
.. |kernel-socname| replace:: imx8mp
.. |kernel-tag| replace:: v6.6.21-phy1
.. |emmcdev| replace:: mmcblk2
.. Bootloader
.. |u-boot-offset| replace:: 32
.. |u-boot-offset-boot-part| replace:: 0
.. |u-boot-mmc-flash-offset| replace:: 0x40
.. |u-boot-emmc-devno| replace:: 2
.. IMX8(MP) specific
.. |u-boot-socname-config| replace:: IMX8MP
.. |u-boot-tag| replace:: v2024.01-phy3
.. Devicetree
.. |dt-carrierboard| replace:: imx8mp-phyboard-pollux-rdk
.. |dt-som| replace:: imx8mp-phycore-som
.. |dtbo-rpmsg| replace:: imx8mp-phycore-rpmsg.dtbo
.. IMX8(MP) specific
.. |dt-somnetwork| replace:: https://github.com/phytec/linux-phytec/blob/v6.6.21-phy1/arch/arm64/boot/dts/freescale/imx8mp-phycore-som.dtsi#L41
.. Yocto
.. |yocto-bootenv-link| replace:: :yocto-bootenv:`kirkstone`
.. |yocto-bsp-name| replace:: BSP-Yocto-IMX8MP
.. _yocto-bsp-name: `dl-server`_
.. |yocto-codename| replace:: master
.. |yocto-distro| replace:: ampliphy-xwayland
.. |yocto-imagename| replace:: phytec-qt6demo-image
.. |yocto-imageext| replace:: rootfs.wic
.. |yocto-machinename| replace:: phyboard-pollux-imx8mp-3
.. |yocto-manifestname| replace:: BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.1
.. |yocto-manifestname-master| replace:: BSP-Yocto-Ampliphy-i.MX8MP-master
.. |yocto-manifestname-y| replace:: BSP-Yocto-Ampliphy-i.MX8MP-PD24.1.1
.. |yocto-ref-manual| replace:: Yocto Reference Manual (master)
.. _yocto-ref-manual: https://phytec.github.io/doc-bsp-yocto/yocto/manual-index.html#kirkstone
.. _yocto-ref-manual-kernel-and-bootloader-config: https://phytec.github.io/doc-bsp-yocto/yocto/scarthgap.html#kernel-and-bootloader-configuration
.. Ref Substitutions
.. |ref-bootswitch| replace:: :ref:`bootmode switch (S3) <imx8mp-mainline-head-bootswitch>`
.. |ref-bsp-images| replace:: :ref:`BSP Images <imx8mp-mainline-head-images>`
.. |ref-debugusbconnector| replace:: :ref:`(X1) <imx8mp-mainline-head-components>`
.. |ref-dt| replace:: :ref:`device tree <imx8mp-mainline-head-device-tree>`
.. |ref-getting-started| replace:: :ref:`Getting Started <imx8mp-mainline-head-getting-started>`
.. |ref-network| replace:: :ref:`Network Environment Customization <imx8mp-mainline-head-network>`
.. |ref-setup-network-host| replace:: :ref:`Setup Network Host <imx8mp-mainline-head-development>`
.. |ref-usb-otg| replace:: :ref:`X5 (upper connector) <imx8mp-mainline-head-components>`
.. |ref-disable-emmc-part| replace:: :ref:`Disable booting from eMMC boot partitions <emmc-disable-boot-part>`
.. IMX8(MP) specific
.. |sbc-network| replace::
The device tree set up for EQOS Ethernet IP core where the PHY is populated
on the |sbc| can be found here:
https://github.com/phytec/linux-phytec/blob/v6.6.21-phy1/arch/arm64/boot/dts/freescale/imx8mp-phyboard-pollux-rdk.dts#L106
.. |pollux-fan-note| replace::
Starting with BSP-Yocto-i.MX8MP-PD22.1.1 we have to switch from PWM fan
to GPIO fan due to availability. The PWM fan will not be supported
anymore and will not function with the new release.
.. |ref-serial| replace:: :ref:`X2 <imx8mp-head-components>`
.. |ref-jp3| replace:: :ref:`JP3 <imx8mp-head-components>`
.. |ref-jp4| replace:: :ref:`JP4 <imx8mp-head-components>`
.. M-Core specific
.. |mcore| replace:: M7 Core
.. |mcore-zephyr-docs| replace:: https://docs.zephyrproject.org/latest/boards/phytec/mimx8mp_phyboard_pollux/doc/index.html
.. |mcore-jtag-dev| replace:: MIMX8MM6_M4
.. |mcore-sdk-version| replace:: 2.13.0
+-----------------------+----------------------+
| |doc-id| |soc| BSP | |
| ManualHead | |
+-----------------------+----------------------+
| Document Title | |doc-id| |soc| BSP |
| | Mainline Manual Head |
+-----------------------+----------------------+
| Document Type | BSP Manual |
+-----------------------+----------------------+
| Article Number | |doc-id| |
+-----------------------+----------------------+
| Yocto Manual | |
+-----------------------+----------------------+
| Release Date | XXXX/XX/XX |
+-----------------------+----------------------+
| Is Branch of | |doc-id| |soc| BSP |
| | Mainline Manual Head |
+-----------------------+----------------------+
The table below shows the Compatible BSPs for this manual:
================ ================ ================= ==========
Compatible BSP'S BSP Release Type BSP Release Date BSP Status
================ ================ ================= ==========
..
================ ================ ================= ==========
.. include:: ../../intro.rsti
Supported Hardware
------------------
On our web page, you can see all supported Machines with the available Article
Numbers for this release: |yocto-manifestname| `download <dlpage-bsp_>`_.
If you choose a specific **Machine Name** in the section **Supported Machines**,
you can see which **Article Numbers** are available under this machine and also
a short description of the hardware information. In case you only have
the **Article Number** of your hardware, you can leave the **Machine
Name** drop-down menu empty and only choose your **Article Number**. Now it
should show you the necessary **Machine Name** for your specific hardware
.. _imx8mp-mainline-head-components:
.. include:: components.rsti
.. +---------------------------------------------------------------------------+
.. Getting Started
.. +---------------------------------------------------------------------------+
.. _imx8mp-mainline-head-getting-started:
Getting Started
===============
The |kit| is shipped with a pre-flashed SD card. It contains the
|yocto-imagename| and can be used directly as a boot source. The eMMC is
programmed with only a U-Boot by default. You can get all sources from the
`PHYTEC download server <dl-server_>`_. This chapter explains how to flash a BSP
image to SD card and how to start the board.
There are several ways to flash an image to SD card or even eMMC. Most notably
using simple, sequential writing with the Linux command line tool ``dd``. An
alternative way is to use PHYTEC's system initialization program called
`partup <https://github.com/phytec/partup>`_, which makes it especially easy to
format more complex systems. You can get `prebuilt Linux binaries of partup
<https://github.com/phytec/partup/releases>`__ from its release page. Also read
`partup's README <https://github.com/phytec/partup#readme>`__ for installation
instructions.
Get the Image
-------------
The image contains all necessary files and makes sure partitions and any raw
data are correctly written. Both the partup package and the WIC image, which can
be flashed using ``dd``, can be downloaded from the `PHYTEC download server
<dl-server_>`_.
Get either the partup package or the WIC image from the download server:
.. code-block:: console
:substitutions:
host:~$ wget |link-partup-package|
host:~$ wget |link-image|
.. note::
For eMMC, more complex partitioning schemes or even just large images, we
recommend using the partup package, as it is faster in writing than ``dd``
and allows for a more flexible configuration of the target flash device.
Write the Image to SD Card
--------------------------
.. warning::
To create your bootable SD card, you must have root privileges on your Linux
host PC. Be very careful when specifying the destination device! All files
on the selected device will be erased immediately without any further query!
Selecting the wrong device may result in **data loss** and e.g. could erase
your currently running system on your host PC!
Finding the Correct Device
..........................
To create your bootable SD card, you must first find the correct device name
of your SD card and possible partitions. If any partitions of the SD cards are
mounted, unmount those before you start copying the image to the SD card.
#. In order to get the correct device name, remove your SD card and
execute:
.. code-block:: console
host:~$ lsblk
#. Now insert your SD card and execute the command again:
.. code-block:: console
host:~$ lsblk
#. Compare the two outputs to find the new device names listed in the second
output. These are the device names of the SD card (device and partitions if
the SD card was formatted).
#. In order to verify the device names being found, execute the command
``sudo dmesg``. Within the last lines of its output, you should also find the
device names, e.g. ``/dev/sde`` or ``/dev/mmcblk0`` (depending on your
system).
Alternatively, you may use a graphical program of your choice, like `GNOME Disks
<https://apps.gnome.org/en/DiskUtility/>`_ or `KDE Partition Manager
<https://apps.kde.org/partitionmanager/>`_, to find the correct device.
Now that you have the correct device name, e.g. ``/dev/sde``,
you can see the partitions which must be unmounted if the SD card is formatted.
In this case, you will also find the device name with an appended number
(e.g. ``/dev/sde1``) in the output. These represent the partitions. Some Linux
distributions automatically mount partitions when the device gets plugged in.
Before writing, however, these need to be unmounted to avoid data corruption.
Unmount all those partitions, e.g.:
.. code-block:: console
host:~$ sudo umount /dev/sde1
host:~$ sudo umount /dev/sde2
Now, the SD card is ready to be flashed with an image, using either ``partup``,
``dd`` or ``bmap-tools``.
Using bmap-tools
................
One way to prepare an SD card is using
`bmap-tools <https://github.com/yoctoproject/bmaptool>`_. Yocto
automatically creates a block map file (``<IMAGENAME>-<MACHINE>.wic.bmap``) for
the WIC image that describes the image content and includes checksums for data
integrity. *bmaptool* is packaged by various Linux distributions. For
Debian-based systems install it by issuing:
.. code-block:: console
host:~$ sudo apt install bmap-tools
Flash a WIC image to SD card by calling:
.. code-block:: console
:substitutions:
host:~$ bmaptool copy |yocto-imagename|-|yocto-machinename|.|yocto-imageext| /dev/<your_device>
Replace <your_device> with your actual SD card's device name found previously,
and make sure to place the file ``<IMAGENAME>-<MACHINE>.wic.bmap`` alongside
the regular WIC image file, so bmaptool knows which blocks to write and which
to skip.
.. warning::
*bmaptool* only overwrites the areas of an SD card where image data is
located. This means that a previously written U-Boot environment may still be
available after writing the image.
Using partup
............
Writing to an SD card with partup is done in a single command:
.. code-block:: console
:substitutions:
host:~$ sudo partup install |yocto-imagename|-|yocto-machinename|.rootfs.partup /dev/<your_device>
Make sure to replace <your_device> with your actual device name found previously.
Further usage of partup is explained at its `official documentation website
<https://partup.readthedocs.io/en/latest/>`__.
.. warning::
Host systems which are using resize2fs version 1.46.6 and older
(e.g. Ubuntu 22.04) are not able to write partup packages created with Yocto Mickledore
or newer to SD-Card. This is due to a new default option in resize2fs which causes an
incompatibility. See `release notes <https://e2fsprogs.sourceforge.net/e2fsprogs-release.html#1.47.0>`_.
.. note::
*partup* has the advantage of allowing to clear specific raw areas in the
MMC user area, which is used in our provided partup packages to erase any
existing U-Boot environments. This is a known issue *bmaptool* does not
solve, as mentioned in the previous chapter.
Another key advantage of partup over other flashing tools is that it allows
configuring MMC specific parts, like writing to eMMC boot partitions, without
the need to call multiple other commands when writing.
Using ``dd``
............
After having unmounted all SD card's partitions, you can create your bootable SD card.
Some PHYTEC BSPs produce uncompressed images (with filename-extension \*.wic),
and some others produce compressed images (with filename-extension \*.wic.xz).
To flash an uncompressed images (\*.wic) use command below:
.. code-block:: console
:substitutions:
host:~$ sudo dd if=|yocto-imagename|-|yocto-machinename|.|yocto-imageext| of=/dev/<your_device> bs=1M conv=fsync status=progress
Or to flash a compressed images (\*.wic.xz) use that command:
.. code-block:: console
:substitutions:
host:~$ xzcat |yocto-imagename|-|yocto-machinename|.|yocto-imageext|.xz | sudo dd of=/dev/<your_device> bs=1M conv=fsync status=progress
Again, make sure to replace <your_device> with your actual device name found
previously.
The parameter ``conv=fsync`` forces a sync operation on the device before
``dd`` returns. This ensures that all blocks are written to the SD card and
none are left in memory. The parameter ``status=progress`` will print out
information on how much data is and still has to be copied until it is
finished.
First Start-up
--------------
* To boot from an SD card, the |ref-bootswitch| needs to be set to the following
position:
.. image:: images/SD_Card_Boot.png
* Insert the SD card
* Connect the target and the host with **mirco USB** on |ref-debugusbconnector|
debug USB
* Power up the board
.. +---------------------------------------------------------------------------+
.. Building the BSP
.. +---------------------------------------------------------------------------+
.. include:: /bsp/building-bsp.rsti
.. _imx8mp-mainline-head-images:
* **u-boot.bin**: Binary compiled U-boot bootloader (U-Boot). Not the final
Bootloader image!
* **oftree**: Default kernel device tree
* **u-boot-spl.bin**: Secondary program loader (SPL)
* **bl31-imx8mp.bin**: ARM Trusted Firmware binary
* **lpddr4_pmu_train_1d_dmem_202006.bin,
lpddr4_pmu_train_1d_imem_202006.bin,
lpddr4_pmu_train_2d_dmem_202006.bin,
lpddr4_pmu_train_2d_imem_202006.bin**: DDR PHY firmware images
* **Image**: Linux kernel image
* **Image.config**: Kernel configuration
* **imx8mp-phyboard-pollux-rdk*.dtb**: Kernel device tree file
* **phytec-qt6demo-image\*.tar.gz**: Root file system
* **phytec-qt6demo-image\*.wic**: SD card image
.. +---------------------------------------------------------------------------+
.. INSTALLING THE OS
.. +---------------------------------------------------------------------------+
Installing the OS
=================
Bootmode Switch (S3)
--------------------
.. tip::
Hardware revision baseboard: 1552.2
The |sbc| features a boot switch with four individually switchable ports to
select the phyCORE-|soc| default bootsource.
.. _imx8mp-mainline-head-bootswitch:
.. include:: bootmode-switch.rsti
Flash eMMC
----------
To boot from eMMC, make sure that the BSP image is flashed correctly to the eMMC
and the |ref-bootswitch| is set to **eMMC**.
.. warning::
When eMMC and SD card are flashed with the same (identical) image, the UUIDs
of the boot partitions are also identical. If the SD card is connected when
booting, this leads to non-deterministic behavior as Linux mounts the boot
partition based on UUID.
.. code-block:: console
target:~$ blkid
can be run to inspect whether the current setup is affected. If ``mmcblk2p1``
and ``mmcblk1p1`` have an identical UUID, the setup is affected.
Flash eMMC from Network
.......................
|soc| boards have an Ethernet connector and can be updated over a network. Be
sure to set up the development host correctly. The IP needs to be set to
192.168.3.10, the netmask to 255.255.255.0, and a TFTP server needs to be
available. From a high-level point of view, an eMMC device is like an SD card.
Therefore, it is possible to flash the **WIC image** (``<name>.wic``) from
the Yocto build system directly to the eMMC. The image contains the
bootloader, kernel, device tree, device tree overlays, and root file system.
Flash eMMC from Network in U-Boot on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These steps will show how to update the eMMC via a network.
.. tip::
A working network is necessary! |ref-setup-network-host|
* Load your image via network to RAM:
.. code-block::
:substitutions:
u-boot=> dhcp ${loadaddr} |yocto-imagename|-|yocto-machinename|.|yocto-imageext|
BOOTP broadcast 1
DHCP client bound to address 192.168.3.11 (101 ms)
Using ethernet@30be0000 device
TFTP from server 192.168.3.10; our IP address is 192.168.3.11
Filename '|yocto-imagename|-|yocto-machinename|.|yocto-imageext|'.
Load address: 0x40480000
Loading: ######################################
######################################
######################################
...
...
...
######################################
#############
11.2 MiB/s
done
Bytes transferred = 911842304 (36599c00 hex)
* Write the image to the eMMC:
.. code-block::
u-boot=> mmc dev 2
switch to partitions #0, OK
mmc2(part 0) is current device
u-boot=> setexpr nblk ${filesize} / 0x200
u-boot=> mmc write ${loadaddr} 0x0 ${nblk}
MMC write: dev # 2, block # 0, count 1780942 ... 1780942 blocks written: OK
Flash eMMC via Network in Linux on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can update the eMMC from your target.
.. tip::
A working network is necessary! |ref-setup-network-host|
Take a compressed or uncompressed image on the host and send it with ssh through
the network (then uncompress it, if necessary) to the eMMC of the target with a
one-line command:
.. code-block:: console
:substitutions:
target:~$ ssh <USER>@192.168.3.10 "dd if=<path_to_file>/|yocto-imagename|-|yocto-machinename|.|yocto-imageext|" | dd of=/dev/mmcblk2 conv=fsync
Flash eMMC via Network in Linux on Host
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is also possible to install the OS at eMMC from your Linux host. As before,
you need a complete image on your host.
.. tip::
A working network is necessary! |ref-setup-network-host|
Show your available image files on the host:
.. code-block:: console
:substitutions:
host:~$ ls
|yocto-imagename|-|yocto-machinename|.|yocto-imageext|
Send the image with the ``dd`` command combined with ssh through the network
to the eMMC of your device:
.. code-block:: console
:substitutions:
host:~$ dd if=|yocto-imagename|-|yocto-machinename|.|yocto-imageext| status=progress | ssh root@192.168.3.11 "dd of=/dev/mmcblk2 conv=fsync"
Flash eMMC U-Boot image via Network from running U-Boot
.......................................................
Update the standalone U-Boot image imx-boot is also possible from U-Boot. This
can be used if the bootloader on eMMC is located in the eMMC user area.
.. tip::
A working network is necessary! |ref-setup-network-host|
Load image over tftp into RAM and then write it to eMMC:
.. code-block::
:substitutions:
u-boot=> dhcp ${loadaddr} imx-boot
u-boot=> setexpr nblk ${filesize} / 0x200
u-boot=> mmc dev 2
u-boot=> mmc write ${loadaddr} |u-boot-mmc-flash-offset| ${nblk}
.. hint::
The hexadecimal value represents the offset as a multiple of 512 byte
blocks. See the `offset table <#offset-table>`__ for the correct value
of the corresponding SoC.
Flash eMMC from USB
...................
Flash eMMC from USB in U-Boot on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note::
Only the lower USB-A port is configured for storage devices and only
this port will work when trying to access a storage device in U-Boot.
.. tip::
This step only works if the size of the image file is less than 1GB due to
limited usage of RAM size in the Bootloader after enabling OPTEE.
These steps will show how to update the eMMC via a USB device. Configure the
|ref-bootswitch| to SD Card and insert an SD card. Power on the board and stop
in U-Boot prompt. Insert a USB device with the copied WIC image to the USB slot.
Load your image from the USB device to RAM:
.. code-block::
u-boot=> usb start
starting USB...
USB0: USB EHCI 1.00
scanning bus 0 for devices... 2 USB Device(s) found
scanning usb for storage devices... 1 Storage Device(s) found
u-boot=> fatload usb 0:1 ${loadaddr} *.wic
497444864 bytes read in 31577 ms (15 MiB/s)
Write the image to the eMMC:
.. code-block::
u-boot=> mmc dev 2
switch to partitions #0, OK
mmc2(part 0) is current device
u-boot=> setexpr nblk ${filesize} / 0x200
u-boot=> mmc write ${loadaddr} 0x0 ${nblk}
MMC write: dev # 2, block # 0, count 1024000 ... 1024000 blocks written: OK
u-boot=> boot
Flash eMMC from USB in Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These steps will show how to flash the eMMC on Linux with a USB stick. You only
need a complete image saved on the USB stick and a bootable WIC image. (e.g.
|yocto-imagename|-|yocto-machinename|.\ |yocto-imageext|). Set the |ref-bootswitch| to SD Card.
* Insert and mount the USB stick:
.. code-block:: console
[ 60.458908] usb-storage 1-1.1:1.0: USB Mass Storage device detected
[ 60.467286] scsi host0: usb-storage 1-1.1:1.0
[ 61.504607] scsi 0:0:0:0: Direct-Access 8.07 PQ: 0 ANSI: 2
[ 61.515283] sd 0:0:0:0: [sda] 3782656 512-byte logical blocks: (1.94 GB/1.80 GiB)
[ 61.523285] sd 0:0:0:0: [sda] Write Protect is off
[ 61.528509] sd 0:0:0:0: [sda] No Caching mode page found
[ 61.533889] sd 0:0:0:0: [sda] Assuming drive cache: write through
[ 61.665969] sda: sda1
[ 61.672284] sd 0:0:0:0: [sda] Attached SCSI removable disk
target:~$ mount /dev/sda1 /mnt
* Now show your saved image files on the USB Stick:
.. code-block:: console
:substitutions:
target:~$ cd /mnt
target:~$ ls
|yocto-imagename|-|yocto-machinename|.|yocto-imageext|
* Show list of available MMC devices:
.. code-block:: console
target:~$ ls /dev | grep mmc
mmcblk1
mmcblk1p1
mmcblk1p2
mmcblk2
mmcblk2boot0
mmcblk2boot1
mmcblk2p1
mmcblk2p2
mmcblk2rpmb
* The eMMC device can be recognized by the fact that it contains two boot
partitions: (mmcblk2boot0; mmcblk2boot1)
* Write the image to the phyCORE-|soc| eMMC (MMC device 2 without partition):
.. code-block:: console
:substitutions:
target:~$ dd if=|yocto-imagename|-|yocto-machinename|.|yocto-imageext| of=/dev/mmcblk2 conv=fsync
* After a complete write, your board can boot from eMMC.
.. tip::
Before this will work, you need to configure the |ref-bootswitch| to
**eMMC**.
Flash eMMC from SD Card
.......................
Even if there is no network available, you can update the eMMC. For that, you
only need a ready-to-use image file (``*.wic``) located on the SD card.
Because the image file is quite large, you have to enlarge your SD card to use
its full space (if it was not enlarged before). To enlarge your SD card, see
Resizing ext4 Root Filesystem.
Alternatively, flash a partup package to the SD card, as described in
|ref-getting-started|. This will ensure the full space of the SD card is used.
Flash eMMC from SD card in U-Boot on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tip::
This step only works if the size of the image file is less than 1GB due to
limited usage of RAM size in the Bootloader after enabling OPTEE. If the
image file is too large use the `Updating eMMC from SD card in
Linux on Target` subsection.
* Flash an SD card with a working image and create a third FAT partition. Copy
the WIC image (for example |yocto-imagename|.\ |yocto-imageext|) to this
partition.
* Configure the |ref-bootswitch| to SD Card and insert the SD Card.
* Power on the board and stop in U-Boot.
* Load the image:
.. code-block::
:substitutions:
u-boot=> fatload mmc 1:3 ${loadaddr} |yocto-imagename|-|yocto-machinename|.|yocto-imageext|
reading
911842304 bytes read in 39253 ms (22.2 MiB/s)
* Switch the mmc dev to eMMC:
.. code-block::
u-boot=> mmc list
FSL_SDHC: 1 (SD)
FSL_SDHC: 2 (eMMC)
u-boot=> mmc dev 2
switch to partitions #0, OK
mmc2(part 0) is current device
* Flash your WIC image (for example |yocto-imagename|.\ |yocto-imageext|)
from the SD card to eMMC. This will partition the card and copy imx-boot,
Image, dtb, dtbo, and root file system to eMMC.
.. code-block::
u-boot=> setexpr nblk ${filesize} / 0x200
u-boot=> mmc write ${loadaddr} 0x0 ${nblk}
MMC write: dev # 2, block # 0, count 1780942 ... 1780942 blocks written: OK
* Power off the board and change the |ref-bootswitch| to eMMC.
Flash eMMC from SD card in Linux on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also flash the eMMC on Linux. You only need a partup package or WIC
image saved on the SD card.
* Show your saved partup package or WIC image files on the SD card:
.. code-block:: console
:substitutions:
target:~$ ls
|yocto-imagename|-|yocto-machinename|.rootfs.partup
|yocto-imagename|-|yocto-machinename|.|yocto-imageext|
* Show list of available MMC devices:
.. code-block:: console
target:~$ ls /dev | grep mmc
mmcblk1
mmcblk1p1
mmcblk1p2
mmcblk2
mmcblk2boot0
mmcblk2boot1
mmcblk2p1
mmcblk2p2
mmcblk2rpmb
* The eMMC device can be recognized by the fact that it contains two boot
partitions: (mmcblk2\ **boot0**; mmcblk2\ **boot1**)
* Write the image to the phyCORE-|soc| eMMC (MMC device 2 **without**
partition) using `partup`_:
.. code-block:: console
:substitutions:
target:~$ partup install |yocto-imagename|-|yocto-machinename|.rootfs.partup /dev/mmcblk2
Flashing the partup package has the advantage of using the full capacity of
the eMMC device, adjusting partitions accordingly.
.. note::
Alternatively, ``dd`` may be used instead:
.. code-block:: console
:substitutions:
target:~$ dd if=|yocto-imagename|-|yocto-machinename|.|yocto-imageext| of=/dev/mmcblk2 conv=fsync
Keep in mind that the root partition does not make use of the full space when
flashing with ``dd``.
* After a complete write, your board can boot from eMMC.
.. warning::
Before this will work, you need to configure the |ref-bootswitch| to eMMC.
RAUC
----
The RAUC (Robust Auto-Update Controller) mechanism support has been added to
meta-ampliphy. It controls the procedure of updating a device with new firmware.
This includes updating the Linux kernel, Device Tree, and root filesystem.
PHYTEC has written an online manual on how we have intergraded RAUC into our
BSPs: `L-1006e.A5 RAUC Update & Device Management Manual
<https://www.phytec.de/cdocuments/?doc=fgByJg>`__.
.. +---------------------------------------------------------------------------+
.. DEVELOPMENT
.. +---------------------------------------------------------------------------+
.. _imx8mp-mainline-head-development:
Development
===========
.. include:: /bsp/imx-common/development/host_network_setup.rsti
Booting the Kernel from a Network
---------------------------------
Booting from a network means loading the kernel and device tree over TFTP and
the root file system over NFS. The bootloader itself must already be loaded from
another available boot device.
Place Images on Host for Netboot
................................
* Copy the kernel image to your tftp directory:
.. code-block:: console
host:~$ cp Image /srv/tftp
* Copy the devicetree to your tftp directory:
.. code-block:: console
host:~$ cp oftree /srv/tftp
* Make sure other users have read access to all the files in the tftp directory,
otherwise they are not accessible from the target:
.. code-block:: console
host:~$ sudo chmod -R o+r /srv/tftp
* Extract the rootfs to your nfs directory:
.. code-block:: console
:substitutions:
host:~$ sudo tar -xvzf |yocto-imagename|-|yocto-machinename|.tar.gz -C /srv/nfs
.. note::
Make sure you extract with sudo to preserve the correct ownership.
Booting from an Embedded Board
..............................
Boot the board into the U-boot prompt and press any key to hold.
* To boot from a network, call:
.. code-block:: console
u-boot=> run netboot
Working with UUU-Tool
---------------------
The Universal Update Utility Tool (UUU-Tool) from NXP is a software to execute
on the host to load and run the bootloader on the board through SDP (Serial
Download Protocol). For detailed information visit
https://github.com/nxp-imx/mfgtools or download the `Official UUU-tool
documentation <https://community.nxp.com/pwmxy87654/attachments/pwmxy87654/imx-processors/140261/1/UUU.pdf>`_.
Host preparations for UUU-Tool Usage
....................................
* Follow the instructions from https://github.com/nxp-imx/mfgtools#linux.
* If you built UUU from source, add it to ``PATH``:
This BASH command adds UUU only temporarily to ``PATH``. To add it permanently, add this line to
``~/.bashrc``.
.. code-block:: console
export PATH=~/mfgtools/uuu/:"$PATH"
* Set udev rules (documented in ``uuu -udev``):
.. code-block:: console
host:~$ sudo sh -c "uuu -udev >> /etc/udev/rules.d/70-uuu.rules"
host:~$ sudo udevadm control --reload
Get Images
..........
Download imx-boot from our server or get it from your Yocto build directory at
build/deploy/images/|yocto-machinename|/. For flashing a wic image to eMMC,
you will also need |yocto-imagename|-|yocto-machinename|.\ |yocto-imageext|
Prepare Target
..............
Set the |ref-bootswitch| to **USB Serial Download**. Also, connect USB port
|ref-usb-otg| to your host.
Starting bootloader via UUU-Tool
................................
Execute and power up the board:
.. code-block:: console
host:~$ sudo uuu -b spl imx-boot
You can see the bootlog on the console via |ref-debugusbconnector|, as usual.
.. note::
The default boot command when booting with UUU-Tool is set to fastboot. If
you want to change this, please adjust the environment variable bootcmd_mfg
in U-boot prompt with setenv bootcmd_mfg. Please note, when booting with
UUU-tool the default environment is loaded. Saveenv has no effect. If you
want to change the boot command permanently for UUU-boot, you need to change
this in U-Boot code.
Flashing U-boot Image to eMMC via UUU-Tool
...........................................
.. warning::
UUU flashes U-boot into eMMC BOOT (hardware) boot partitions, and it sets
the BOOT_PARTITION_ENABLE in the eMMC! This is a problem since we want the
bootloader to reside in the eMMC USER partition. Flashing next U-Boot version
.wic image and not disabling BOOT_PARTITION_ENABLE bit will result in device
always using U-boot saved in BOOT partitions. To fix this in U-Boot:
.. code-block:: console
:substitutions:
u-boot=> mmc partconf |u-boot-emmc-devno| 0 0 0
u-boot=> mmc partconf |u-boot-emmc-devno|
EXT_CSD[179], PARTITION_CONFIG:
BOOT_ACK: 0x0
BOOT_PARTITION_ENABLE: 0x0
PARTITION_ACCESS: 0x0
or check |ref-disable-emmc-part| from Linux.
This way the bootloader is still flashed to eMMC BOOT partitions but it is
not used!
When using **partup** tool and ``.partup`` package for eMMC flashing this is
done by default, which makes partup again superior flash option.
Execute and power up the board:
.. code-block:: console
host:~$ sudo uuu -b emmc imx-boot
Flashing wic Image to eMMC via UUU-Tool
...........................................
Execute and power up the board:
.. code-block:: console
:substitutions:
host:~$ sudo uuu -b emmc_all imx-boot |yocto-imagename|-|yocto-machinename|.|yocto-imageext|
.. include:: /bsp/imx8/development/development_manifests.rsti
.. standalone build needs to be reworked (maybe more generic to make this file
reuse it)
.. include:: /bsp/imx8/development/upstream_manifest.rsti
Format SD-Card
--------------
Most images are larger than the default root partition. To flash any storage
device with SD Card, the rootfs needs to be expanded or a separate partition
needs to be created. There are some different ways to format the SD Card. The
easiest way to do this is to use the UI program Gparted.
Gparted
.......
* Get GParted:
.. code-block:: console
host:~$ sudo apt install gparted
* Insert the SD Card into your host and get the device name:
.. code-block:: console
host:~$ dmesg | tail
...
[30436.175412] sd 4:0:0:0: [sdb] 62453760 512-byte logical blocks: (32.0 GB/29.8 GiB)
[30436.179846] sdb: sdb1 sdb2
...
* Unmount all SD Card partitions.
* Launch GParted:
.. code-block:: console
host:~$ sudo gparted
.. image:: /bsp/imx-common/images/gparted1.png
Expand rootfs
~~~~~~~~~~~~~
.. warning::
Running gparted on host systems which are using resize2fs version 1.46.6 and older
(e.g. Ubuntu 22.04) are not able to expand the ext4 partition created with Yocto
Mickledore and newer.
This is due to a new default option in resize2fs which causes a incompatibility.
See `release notes <https://e2fsprogs.sourceforge.net/e2fsprogs-release.html#1.47.0>`_.
* Choose your SD Card device at the drop-down menu on the top right
* Choose the ext4 root partition and click on resize: