-
Notifications
You must be signed in to change notification settings - Fork 0
/
pd22.1.1.rst
1756 lines (1231 loc) · 59.3 KB
/
pd22.1.1.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-NXP-i.MX8MM-PD22.1.1
.. |dlpage-product| replace:: https://www.phytec.de/produkte/system-on-modules/phycore-imx-8m-mini/nano/#downloads
.. _dl-server: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MM/
.. _dl-sdk: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MM/BSP-Yocto-NXP-i.MX8MM-PD22.1.1/sdk/ampliphy-vendor-xwayland/
.. |link-image| replace:: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MM/BSP-Yocto-NXP-i.MX8MM-PD22.1.1/images/ampliphy-vendor/phyboard-polis-imx8mn-2/phytec-headless-image-phyboard-polis-imx8mn-2.wic
.. |link-boot-tools| replace:: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MM/BSP-Yocto-NXP-i.MX8MM-PD22.1.1/images/ampliphy-vendor/phyboard-polis-imx8mn-2/imx-boot-tools/
.. _releasenotes: https://git.phytec.de/phy2octo/tree/releasenotes?h=imx8mm
.. IMX8(MN) specific
.. _overlaycallback: https://git.phytec.de/u-boot-imx/tree/board/phytec/phycore_imx8mn/phycore-imx8mn.c?h=v2021.04_2.2.0-phy13
.. General Replacements
.. |atfloadaddr| replace:: 0x960000
.. |kit| replace:: **phyCORE-i.MX8M Nano Kit**
.. |kit-ram-size| replace:: 1GiB
.. |mcore| replace:: M4 Core
.. |sbc| replace:: phyBOARD-Polis
.. |soc| replace:: i.MX 8M Nano
.. |socfamily| replace:: i.MX 8
.. |som| replace:: phyCORE-i.MX8MN
.. |debug-uart| replace:: ttymxc2
.. |serial-uart| replace:: ttymxc0
.. Linux Kernel
.. |kernel-socname| replace:: imx8mn
.. |kernel-tag| replace:: v5.10.72_2.2.0-phy17
.. |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(MN) specific
.. |u-boot-socname-config| replace:: IMX8MN
.. |u-boot-tag| replace:: v2021.04_2.2.0-phy13
.. Devicetree
.. |dt-carrierboard| replace:: imx8mn-phyboard-polis
.. |dt-som| replace:: imx8mn-phycore-som
.. IMX8(MN) specific
.. |dt-somnetwork| replace:: :imx-dt:`imx8mn-phycore-som.dtsi?h=v5.10.72_2.2.0-phy17#n47`
.. Yocto
.. |yocto-bootenv-link| replace:: :yocto-bootenv:`hardknott`
.. |yocto-bsp-name| replace:: BSP-Yocto-IMX8MM
.. _yocto-bsp-name: `dl-server`_
.. |yocto-codename| replace:: hardknott
.. |yocto-distro| replace:: ampliphy-vendor
.. |yocto-imagename| replace:: phytec-headless-image
.. |yocto-machinename| replace:: phyboard-polis-imx8mn-2
.. |yocto-manifestname| replace:: BSP-Yocto-NXP-i.MX8MM-PD22.1.1
.. |yocto-manifestname-master| replace:: BSP-Yocto-Ampliphy-i.MX8MM-master
.. |yocto-manifestname-y| replace:: BSP-Yocto-NXP-i.MX8MM-PD22.1.y
.. |yocto-ref-manual| replace:: L-813e.A12 Yocto Reference Manual (Hardknott)
.. _yocto-ref-manual: https://www.phytec.de/cdocuments/?doc=UIHsG
.. _yocto-ref-manual-kernel-and-bootloader-config: https://www.phytec.de/cdocuments/?doc=UIHsG#YoctoReferenceManualHardknottL813e-A12-KernelandBootloaderConfiguration
.. Refs
.. |ref-bootswitch| replace:: :ref:`bootmode switch (S1) <imx8mn-pd22.1.1-bootswitch>`
.. |ref-bsp-images| replace:: :ref:`BSP Images <imx8mn-pd22.1.1-images>`
.. |ref-debugusbconnector| replace:: :ref:`(X30) <imx8mn-pd22.1.1-components>`
.. |ref-dt| replace:: :ref:`device tree <imx8mn-pd22.1.1-device-tree>`
.. |ref-network| replace:: :ref:`Network Environment Customization <imx8mn-pd22.1.1-network>`
.. |ref-setup-network-host| replace:: :ref:`Setup Network Host <imx8mn-pd22.1.1-development>`
.. |ref-usb-otg| replace:: :ref:`X2 <imx8mn-pd22.1.1-components>`
.. |ref-disable-emmc-part| replace:: :ref:`Disable booting from eMMC boot partitions <emmc-disable-boot-part>`
.. IMX8(MN) specific replacements
.. |sbc-network| replace:: \
.. |pollux-fan-note| replace:: Only GPIO fan supported.
.. |ubootexternalenv| replace:: U-boot External Environment subsection of the
:ref:`device tree overlay section <imx8mn-pd22.1.1-ubootexternalenv>`
+----------------------+----------------------+
| |soc| BSP Manual |
+----------------------+----------------------+
| Document Title | |soc| BSP Manual |
+----------------------+----------------------+
| Document Type | BSP Manual |
+----------------------+----------------------+
| Yocto Manual | |
+----------------------+----------------------+
| Release Date | 2023/05/25 |
+----------------------+----------------------+
| Is Branch of | |soc| BSP Manual |
+----------------------+----------------------+
The table below shows the Compatible BSPs for this manual:
==================== ================ ================= ==========
Compatible BSP'S BSP Release Type BSP Release Date BSP Status
==================== ================ ================= ==========
|yocto-manifestname| Minor 2023/05/23 Released
==================== ================ ================= ==========
.. include:: ../../intro.rsti
Supported Hardware
------------------
The |sbc| populated with the |soc| SoC is supported.
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
.. _imx8mn-pd22.1.1-components:
.. include:: ../imx8mm/components.rsti
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.
Get the Image
-------------
The WIC image contains all BSP files in several, correctly pre-formatted
partitions and can be copied to an SD card easily using the single Linux
command ``dd``. It can be built by Yocto or downloaded from the PHYTEC download
server.
Get the WIC file from the download server:
.. code-block:: console
:substitutions:
host:~$ wget |link-image|
Write the Image to SD Card
--------------------------
.. warning::
To create your bootable SD card with the ``dd`` command, you must have root
privileges. Be very careful when specifying the destination device with
``dd``! All files on the selected destination 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!
To create your bootable SD card, you must first find the correct device name
of your SD card and possible partitions. Unmount any mounted partitions before
you start copying the image to the SD card.
#. In order to get the correct device name, remove your SD card and
execute::
host$ lsblk
#. Now insert your SD card and execute the command again::
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 partitions, e.g.::
host$ sudo umount /dev/sde1
* After having unmounted all partitions, you can create your bootable SD card::
host$ sudo dd if=<IMAGENAME>-<MACHINE>.wic of=/dev/sdX bs=1M conv=fsync status=progress
Again, make sure to replace ``/dev/sdX`` 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.
An alternative and much faster way to prepare an SD card can be done by using
`bmap-tools <https://github.com/intel/bmap-tools>`_ from Intel. 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::
host$ sudo apt install bmap-tools
Flash a WIC image to SD card by calling::
host$ bmaptool copy <IMAGENAME>-<MACHINE>.wic /dev/<your_device>
.. 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.
First Start-up
--------------
* To boot from an SD card, |ref-bootswitch| needs to be set to the following
position:
.. list-table:: Bootmode Selection
:align: center
* - .. figure:: images/Nano_SD_BOOT.jpg
:width: 250px
SD Card Boot
* 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
.. _imx8mn-pd22.1.1-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-imx8mm.bin**: ARM Trusted Firmware binary
* **lpddr4_pmu_train_2d_dmem_202006.bin,
lpddr4_pmu_train_2d_imem_202006.bin**: DDR PHY firmware images
* **imx-boot**: Bootloader build by imx-mkimage which includes SPL, U-Boot, ARM
Trusted Firmware and DDR firmware. This is the final bootloader image which is
bootable.
* **Image**: Linux kernel image
* **Image.config**: Kernel configuration
* **imx8mn-phyboard-polis-dsi*.dtb**: Kernel device tree file
* **imx8mn-phy*.dtbo**: Kernel device tree overlay files
* **phytec-headless-image\*.tar.gz**: Root file system
* **phytec-headless-image\*.wic**: SD card image
.. +---------------------------------------------------------------------------+
.. INSTALLING THE OS
.. +---------------------------------------------------------------------------+
Installing the OS
=================
Bootmode Switch (S1)
--------------------
The |sbc| features a boot switch with six individually switchable ports to
select the phyCORE-|soc| default bootsource.
.. _imx8mn-pd22.1.1-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 **Default SOM boot**.
.. 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. However, they only
work if the size of the image file is less than 1GB. If the image file is
larger, go to the section Format SD Card. Configure the |ref-bootswitch| to boot
from SD Card and put in an SD card. Power on the board and stop in U-Boot
prompt.
.. tip::
A working network is necessary! |ref-setup-network-host|
* Load your image via network to RAM:
.. code-block::
:substitutions:
u-boot=> tftp ${loadaddr} |yocto-imagename|-|yocto-machinename|.wic
Using ethernet@30be0000 device
TFTP from server 192.168.3.10; our IP address is 192.168.3.11
Filename '|yocto-imagename|-|yocto-machinename|.wic'.
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! 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|.wic" | dd of=/dev/mmcblk2
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! Setup Network Host.
Show your available image files on the host:
.. code-block:: console
:substitutions:
host:~$ ls
|yocto-imagename|-|yocto-machinename|.wic
Send the image with the command 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|.wic status=progress | ssh root@192.168.3.11 "dd of=/dev/mmcblk2"
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! Setup Network Host.
Load image over tftp into RAM and then write it to eMMC:
.. code-block::
:substitutions:
u-boot=> tftp ${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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tip::
This step only works if the size of the image file is less than 1GB due to
limited usage of RAM size in Bootloader after enabling the OPTEE.
These steps will show how to update the eMMC via a USB device. Configure the
bootmode switch to |ref-bootswitch| and put in 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|.wic). Set the bootmode switch to
|ref-bootswitch|.
* 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|.wic
* 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|.wic of=/dev/mmcblk2
* After a complete write, your board can boot from eMMC.
.. warning::
Before this will work, you need to configure the multi-port switch
to **Default SOM Boot** to |ref-bootswitch|.
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.
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 Bootloader after enabling the 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|.wic) to this
partition.
* Configure the bootmode switch to boot from the SD Card and insert the SD
card.
* Power on the board and stop in u-boot.
* Flash your WIC image (for example |yocto-imagename|.wic)
from the SD card to eMMC. This will partition the card and copy imx-boot,
Image, dtb, dtbo, and root file system to eMMC.
* Load the image:
.. code-block::
:substitutions:
u-boot=> fatload mmc 1:3 ${loadaddr} |yocto-imagename|-|yocto-machinename|.wic
reading
911842304 bytes read in 39253 ms (22.2 MiB/s)
* Switch the mmc dev:
.. code-block::
u-boot=> mmc list
FSL_SDHC: 1 (SD)
FSL_SDHC: 2 (eMMC)
u-boot=> mmc dev 2
switch to partitions #0, OK
mmc0(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
* Power off the board and change the multi-port switch to Default SOM Boot to
boot from eMMC.
Flash eMMC from SD card in Linux on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can also flash the eMMC on Linux. You only need a complete image saved on
the SD card (e.g. |yocto-imagename|-|yocto-machinename|.wic).
* Show your saved image files on the SD card:
.. code-block:: console
:substitutions:
target:~$ ls
|yocto-imagename|-|yocto-machinename|.wic
* 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):
.. code-block:: console
:substitutions:
target:~$ dd if=|yocto-imagename|-|yocto-machinename|.wic of=/dev/mmcblk2
* After a complete write, your board can boot from eMMC.
.. warning::
Before this will work, you need to configure the |ref-bootswitch| to Default
SOM Boot to boot from eMMC.
Flash SPI NOR Flash
-------------------
The |som| modules are optionally equipped with SPI NOR Flash. To boot from SPI
Flash, set |ref-bootswitch| to **QSPI boot** to boot from QSPI. The SPI Flash is
usually quite small. The phyBOARD-Pollux-i.MX8MP kit only has 32MB SPI NOR flash
populated. Only the bootloader and the environment can be stored. The kernel,
device tree, and file system are taken from eMMC by default.
The SPI NOR flash partition table is defined in the U-Boot environment. It can
be printed with:
.. code-block::
u-boot=> printenv mtdparts
mtdparts=30bb0000.spi:3840k(u-boot),128k(env),128k(env:redund),-(none)
Flash SPI NOR Flash from Network
................................
The SPI NOR can contain the bootloader and environment to boot from. The arm64
kernel can not decompress itself, the image size extends the SPI NOR flash
populated on the phyCORE-|soc|.
.. tip::
A working network is necessary! Setup Network Host.
Flash SPI NOR from Network in u-boot on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Similar to updating the eMMC 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. Before reading and
writing is possible, the SPI-NOR flash needs to be probed:
.. code-block::
u-boot=> sf probe
SF: Detected mt25qu512a with page size 256 Bytes, erase size 64 KiB, total 64 MiB
* A specially formatted u-boot image for the SPI NOR flash is used. Ensure you
use the correct image file. Load the image over tftp, erase and write the
bootloader to the flash:
.. code-block::
:substitutions:
u-boot=> tftp ${loadaddr} imx-boot-|yocto-machinename|-fspi.bin-flash_evk_flexspi
u-boot=> sf update ${loadaddr} 0 ${filesize}
device 0 offset 0x0, size 0x1c0b20
1641248 bytes written, 196608 bytes skipped in 4.768s, speed 394459 B/s
* Erase the environment partition as well. This way, the environment can be
written after booting from SPI NOR flash:
.. code-block::
u-boot=> sf erase 0x400000 0x100000
.. warning::
Erasing the complete SPI NOR flash when it is fully written will take quite
some time. This can trigger the watchdog to reset. Due to this, erase the
full flash in Linux.
Flash SPI NOR from Network in kernel on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Copy the image from the host to the target:
.. code-block:: console
:substitutions:
host:~$ scp imx-boot-|yocto-machinename|-fspi.bin-flash_evk_flexspi root@192.168.3.11:/root
* Find the number of erase blocks of the U-boot partition:
.. code-block:: console
target:~$ mtdinfo /dev/mtd0
mtd0
Name: u-boot
Type: nor
Eraseblock size: 65536 bytes, 64.0 KiB
Amount of eraseblocks: 60 (3932160 bytes, 3.7 MiB)
Minimum input/output unit size: 1 byte
Sub-page size: 1 byte
Character device major/minor: 90:0
Bad blocks are allowed: false
Device is writable: true
* Erase the u-boot partition and flash it:
.. code-block:: console
:substitutions:
target:~$ flash_erase /dev/mtd0 0x0 60
target:~$ flashcp imx-boot-|yocto-machinename|-fspi.bin-flash_evk_flexspi /dev/mtd0
Flash SPI NOR Flash from SD Card
................................
The bootloader on SPI NOR flash can be also flashed with SD Card.
Flash SPI NOR from SD Card in u-boot on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Copy the SPI NOR flash U-boot image
imx-boot-|yocto-machinename|-fspi.bin-flash_evk_flexspi to the FAT partition
on the SD Card. Before reading and writing are possible, the SPI-NOR flash
needs to be probed:
.. code-block::
u-boot=> sf probe
SF: Detected n25q256ax1 with page size 256 Bytes, erase size 64 KiB, total 32 MiB
* A specially formatted U-boot image for the SPI NOR flash is used. Ensure you
use the correct image file. Load the image from the SD Card, erase and write
the bootloader to the flash:
.. code-block::
:substitutions:
u-boot=> mmc dev 1
u-boot=> fatload mmc 1:1 ${loadaddr} imx-boot-|yocto-machinename|-fspi.bin-flash_evk_flexspi
u-boot=> sf update ${loadaddr} 0 ${filesize}
* Erase the environment partition as well. This way, the environment can be
written after booting from SPI NOR flash:
.. code-block::
u-boot=> sf erase 0x400000 0x100000
.. warning::
Erasing the complete SPI NOR flash when it is fully written will take quite
some time. This can trigger the watchdog to reset. Due to this, erase the
full flash in Linux.
Flash SPI NOR from SD Card in kernel on Target
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* Mount the SD Card:
.. code-block:: console
:substitutions:
host:~$ mount /dev/mmcblkp1 /mnt
* Find the number of erase blocks of the u-boot partition:
.. code-block:: console
target:~$ mtdinfo /dev/mtd0
mtd0
Name: u-boot
Type: nor
Eraseblock size: 65536 bytes, 64.0 KiB
Amount of eraseblocks: 60 (3932160 bytes, 3.7 MiB)
Minimum input/output unit size: 1 byte
Sub-page size: 1 byte
Character device major/minor: 90:0
Bad blocks are allowed: false
Device is writable: true
* Erase the u-boot partition and flash it:
.. code-block:: console
:substitutions:
target:~$ flash_erase /dev/mtd0 0x0 60
target:~$ flashcp /mnt/imx-boot-|yocto-machinename|-fspi.bin-flash_evk_flexspi /dev/mtd0
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.A3 RAUC Update & Device Management Manual.
.. +---------------------------------------------------------------------------+
.. DEVELOPMENT
.. +---------------------------------------------------------------------------+
.. _imx8mn-pd22.1.1-development:
Development
===========
.. include:: /bsp/imx-common/development/host_network_setup.rsti
.. include:: /bsp/imx-common/development/netboot.rsti
.. include:: /bsp/imx-common/development/uuu.rsti
.. include:: /bsp/imx8/development/standalone_build.rsti
:end-before: .. build-uboot-marker
* Get the U-Boot sources:
.. code-block:: console
host:~$ git clone git://git.phytec.de/u-boot-imx
* To get the correct *U-Boot* **tag** you need to take a look at our release
notes, which can be found here: `release notes <releasenotes_>`_
* The **tag** needed at this release is called |u-boot-tag|
* Check out the needed *U-Boot* **tag**:
.. code-block:: console
:substitutions:
host:~$ cd ~/u-boot-imx/
host:~$ git fetch --all --tags
host:~$ git checkout tags/|u-boot-tag|
* Technically, you can now build the U-Boot, but practically there are some
further steps necessary:
* Create your own development branch:
.. code-block:: console
host:~$ git switch --create <new-branch>
.. note::
You can name your development branch as you like, this is just an example.
* Copy all binaries into the U-Boot build directory
* Set up a build environment:
.. code-block:: console
:substitutions:
host:~$ source /opt/|yocto-distro|/|yocto-manifestname|/environment-setup-cortexa53-crypto-phytec-linux
* Set this environment variable before building the Image:
.. code-block:: console
:substitutions:
host:~$ export ATF_LOAD_ADDR=|atfloadaddr|
* build flash.bin (imx-boot):
.. code-block:: console
:substitutions:
host:~$ make phycore-|kernel-socname|_defconfig
host:~$ make flash.bin
The flash.bin can be found at u-boot-imx/ directory and now can be flashed. A
chip-specific offset is needed:
.. _offset-table:
===== =================== ============================= ============
SoC Offset User Area Offset Boot Partition eMMC Device
===== =================== ============================= ============
|soc| |u-boot-offset| kiB |u-boot-offset-boot-part| kiB /dev/mmcblk2
===== =================== ============================= ============
E.g. flash SD card:
.. code-block:: console
:substitutions:
host:~$ sudo dd if=flash.bin of=/dev/sd[x] bs=1024 seek=|u-boot-offset| conv=sync
.. hint::
The specific offset values are also declared in the Yocto variables "BOOTLOADER_SEEK" and "BOOTLOADER_SEEK_EMMC"
.. include:: /bsp/imx8/development/standalone_build.rsti
:start-after: .. build-kernel-marker
.. include:: /bsp/imx8/development/development_manifests.rsti
.. include:: /bsp/imx8/development/upstream_manifest.rsti
.. include:: /bsp/imx-common/development/format_sd-card.rsti
.. +---------------------------------------------------------------------------+
.. DEVICE TREE
.. +---------------------------------------------------------------------------+
.. _imx8mn-pd22.1.1-device-tree:
Device Tree (DT)
================
Introduction
------------
The following text briefly describes the Device Tree and can be found in
the Linux kernel Documentation
(https://docs.kernel.org/devicetree/usage-model.html)
*"The “Open Firmware Device Tree”, or simply Devicetree (DT), is a data
structure and language for describing hardware. More specifically, it is a
description of hardware that is readable by an operating system so that the
operating system doesn't need to hard code details of the machine."*
The kernel documentation is a really good source for a DT introduction. An
overview of the device tree data format can be found on the device tree usage
page at `devicetree.org <https://www.devicetree.org/>`_.
PHYTEC |soc| BSP Device Tree Concept
------------------------------------
The following sections explain some rules PHYTEC has defined on how to set up
device trees for our |soc| SoC-based boards.
Device Tree Structure
.....................
* *Module.dtsi* - Module includes all devices mounted on the SoM, such as PMIC
and RAM.
* *Carrierboard.dtsi* - Devices that come from the |soc| SoC but are just routed
down to the carrier board and used there are included in this dtsi.
* *Board.dts* - include the carrier board and module dtsi files. There may also
be some hardware configuration nodes enabled on the carrier board or the
module (i.e. the Board .dts shows the special characteristics of the board
configuration). For example, there are phyCORE-|soc| SOMs which may or may not
have a MIPI DSI to LVDS converter mounted. The converter is enabled (if
available) in the Board .dts and not in the Module .dtsi
From the root directory of the Linux Kernel our devicetree files for |socfamily|
platforms can be found in ``arch/arm64/boot/dts/freescale/``.
Device Tree Overlay
...................
Device Tree overlays are device tree fragments that can be merged into a device
tree during boot time. These are for example hardware descriptions of an
expansion board. They are instead of being added to the device tree as an extra
include, now applied as an overlay. They also may only contain setting the
status of a node depending on if it is mounted or not. The device tree overlays
are placed next to the other device tree files in our Linux kernel repository in
the subfolder ``arch/arm64/boot/dts/freescale/overlays``.
Available overlays for |yocto-machinename|.conf are:
.. code-block::
imx8mn-phyboard-polis-peb-eval-01.dtbo
imx8mn-phyboard-polis-peb-av-010.dtbo
imx8mn-phycore-rpmsg.dtbo
imx8mn-phycore-no-eth.dtbo
imx8mn-phycore-no-spiflash.dtbo
imx8mn-vm016.dtbo
imx8mn-vm016-fpdlink.dtbo
imx8mn-vm017.dtbo
imx8mn-vm017-fpdlink.dtbo
imx8mn-dual-vm017-fpdlink.dtbo
.. _imx8mn-pd22.1.1-ubootexternalenv: