diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guru.rst | 17 | ||||
| -rw-r--r-- | doc/hardware.rst | 65 | ||||
| -rw-r--r-- | doc/hardware_mips_qemu.rst | 2 | ||||
| -rw-r--r-- | doc/hardware_mipsel_qemu.rst | 13 | ||||
| -rw-r--r-- | doc/hardware_rpi1_raspi1.rst (renamed from doc/hardware_rpi_raspi1.rst) | 2 | ||||
| -rw-r--r-- | doc/hardware_v7a_beaglebone_black.rst | 2 | ||||
| -rw-r--r-- | doc/hardware_v7a_beaglebone_white.rst | 2 | ||||
| -rw-r--r-- | doc/hardware_v7a_noneon_sama5d3.rst | 22 | ||||
| -rw-r--r-- | doc/hardware_v7a_qemu.rst | 2 | ||||
| -rw-r--r-- | doc/hardware_v7a_raspi2.rst | 15 | ||||
| -rw-r--r-- | doc/hardware_v7a_raspi23.rst (renamed from doc/hardware_v7a_raspi3.rst) | 21 | ||||
| -rw-r--r-- | doc/hardware_v7a_riot.rst | 68 | ||||
| -rw-r--r-- | doc/hardware_v7a_sama5d2.rst | 2 | ||||
| -rw-r--r-- | doc/hardware_v7a_sama5d4.rst | 16 | ||||
| -rw-r--r-- | doc/hardware_v7a_udoo_neo.rst | 2 | ||||
| -rw-r--r-- | doc/hardware_v8a_espressobin.rst | 2 | ||||
| -rw-r--r-- | doc/hardware_v8a_rock3a.rst | 36 | ||||
| -rw-r--r-- | doc/hardware_x86_64_qemu.rst | 2 | ||||
| -rw-r--r-- | doc/index-layer-1-distrokit.rst (renamed from doc/index.rst) | 3 | ||||
| -rw-r--r-- | doc/intro.rst | 30 | ||||
| -rw-r--r-- | doc/testing.rst | 165 |
21 files changed, 425 insertions, 64 deletions
diff --git a/doc/guru.rst b/doc/guru.rst deleted file mode 100644 index 1929464..0000000 --- a/doc/guru.rst +++ /dev/null @@ -1,17 +0,0 @@ -Welcome to the PTXdist Universe -=============================== - -.. toctree:: - :glob: - :maxdepth: 3 - - welcome - environment - user_manual_section - dev_manual - ref_manual - daily_work_section - contributing - getting_help - faq - diff --git a/doc/hardware.rst b/doc/hardware.rst index 117fb17..5c9a0df 100644 --- a/doc/hardware.rst +++ b/doc/hardware.rst @@ -46,10 +46,10 @@ It supports the following hardware: hardware_v7a_beaglebone_black hardware_v7a_nitrogen6x hardware_v7a_riot - hardware_v7a_raspi2 - hardware_v7a_raspi3 + hardware_v7a_raspi23 hardware_v7a_udoo_neo hardware_v7a_sama5d2 + hardware_v7a_sama5d4 If you want to get DistroKit running on your ARMv7-A board which is not listed above, here is a short overview of the generic way: @@ -92,6 +92,25 @@ listed above, here is a short overview of the generic way: Refer to the :ref:`ptx_dev_manual` for a more thorough documentation. +v7a_noneon Platform +------------------- + ++-------------------------+------------------------------------------------+ +| platformconfig: | ``configs/platform-v7a_noneon/platformconfig`` | ++-------------------------+------------------------------------------------+ +| Toolchain architecture: | ``arm-v7a-linux-gnueabihf`` | ++-------------------------+------------------------------------------------+ + +The v7a_noneon platform targets machines based on the ARMv7-A architecture +which don't have support for the NEON SIMD extension. +It supports the following hardware: + +.. toctree:: + :maxdepth: 1 + + hardware_v7a_noneon_sama5d3 + + v8a Platform ------------ @@ -105,38 +124,39 @@ The v8a platform targets the ARMv8-A architecture. The stuff from the v7a section above applies here accordingly. -Currently DistroKit only supports a single board; the Marvell espressobin: +Currently, DistroKit supports the following hardware: .. toctree:: :maxdepth: 1 hardware_v8a_espressobin + hardware_v8a_rock3a -rpi Platform ------------- +rpi1 Platform +------------- -+-------------------------+-----------------------------------------+ -| platformconfig: | ``configs/platform-rpi/platformconfig`` | -+-------------------------+-----------------------------------------+ -| Toolchain architecture: | ``arm-1136jfs-linux-gnueabihf`` | -+-------------------------+-----------------------------------------+ ++-------------------------+------------------------------------------+ +| platformconfig: | ``configs/platform-rpi1/platformconfig`` | ++-------------------------+------------------------------------------+ +| Toolchain architecture: | ``arm-1136jfs-linux-gnueabihf`` | ++-------------------------+------------------------------------------+ .. note:: - The rpi platform is currently not actively maintained, + The rpi1 platform is currently not actively maintained, as RPi 1 has been superseded by newer models which are supported in the v7a platform. However, if you are targeting a RPi 1, we will be happy to merge your patches anyways. -The rpi platform has support for the Raspberry Pi 1 and Raspberry Pi Zero W, +The rpi1 platform has support for the Raspberry Pi 1 and Raspberry Pi Zero W, which is based on the Broadcom BCM2835 SoC (ARMv6): .. toctree:: :maxdepth: 1 - hardware_rpi_raspi1 + hardware_rpi1_raspi1 mips Platform @@ -151,7 +171,22 @@ mips Platform .. toctree:: :maxdepth: 1 - hardware_x86_64_qemu + hardware_mips_qemu + + +mips Platform +------------- + ++-------------------------+--------------------------------------------+ +| platformconfig: | ``configs/platform-mipsel/platformconfig`` | ++-------------------------+--------------------------------------------+ +| Toolchain architecture: | ``mipsel-softfloat-linux-gnu`` | ++-------------------------+--------------------------------------------+ + +.. toctree:: + :maxdepth: 1 + + hardware_mipsel_qemu x86_64 Platform @@ -166,4 +201,4 @@ x86_64 Platform .. toctree:: :maxdepth: 1 - hardware_mips_qemu + hardware_x86_64_qemu diff --git a/doc/hardware_mips_qemu.rst b/doc/hardware_mips_qemu.rst index 657c32f..ca5049f 100644 --- a/doc/hardware_mips_qemu.rst +++ b/doc/hardware_mips_qemu.rst @@ -3,7 +3,7 @@ QEmu The mips platform is ready to run in qemu, using the MIPS Malta board simulation. -There are two ways to run DistoKit inside qemu: +There are two ways to run DistroKit inside qemu: * With barebox: Run ``./configs/platform-mips/run barebox`` to barebox. The barebox should boot diff --git a/doc/hardware_mipsel_qemu.rst b/doc/hardware_mipsel_qemu.rst new file mode 100644 index 0000000..9805a0a --- /dev/null +++ b/doc/hardware_mipsel_qemu.rst @@ -0,0 +1,13 @@ +QEmu +==== + +The mipsel platform is ready to run in qemu, using the MIPS Malta board +simulation. +There are two ways to run DistroKit inside qemu: + +* With barebox: + Run ``./configs/platform-mipsel/run barebox`` to barebox. The barebox should + boot the kernel if supported. +* Without barebox: + Run ``./configs/platform-mipsel/run`` to directly start the kernel without + barebox. diff --git a/doc/hardware_rpi_raspi1.rst b/doc/hardware_rpi1_raspi1.rst index 4a90fdc..19825d9 100644 --- a/doc/hardware_rpi_raspi1.rst +++ b/doc/hardware_rpi1_raspi1.rst @@ -3,7 +3,7 @@ Raspberry Pi 1 and Zero W Boot Media ---------- -Use the image ``platform-rpi/images/hd.img`` and write it onto your SD Card. +Use the image ``platform-rpi1/images/hd.img`` and write it onto your SD Card. Serial Console -------------- diff --git a/doc/hardware_v7a_beaglebone_black.rst b/doc/hardware_v7a_beaglebone_black.rst index bb523b6..f0adfb9 100644 --- a/doc/hardware_v7a_beaglebone_black.rst +++ b/doc/hardware_v7a_beaglebone_black.rst @@ -3,7 +3,7 @@ Beaglebone Black Boot Media ---------- -Use the image ``platform-v7a/images/beaglebone.hdimg`` and copy it onto your MicroSD-Card. +Use the image ``platform-v7a/images/beaglebone.hdimg`` and write it to your MicroSD-Card. Press the user-button ``S2`` when powering up the Beaglebone Black to boot from MicroSD-Card. ``S2`` is the button above the MicroSD-Card. Serial Console diff --git a/doc/hardware_v7a_beaglebone_white.rst b/doc/hardware_v7a_beaglebone_white.rst index 540066b..2ed669b 100644 --- a/doc/hardware_v7a_beaglebone_white.rst +++ b/doc/hardware_v7a_beaglebone_white.rst @@ -3,7 +3,7 @@ Beaglebone White Boot Media ---------- -Use the image ``platform-v7a/images/beaglebone.hdimg`` and copy it onto your MicroSD-Card. +Use the image ``platform-v7a/images/beaglebone.hdimg`` and write it to your MicroSD-Card. Serial Console -------------- diff --git a/doc/hardware_v7a_noneon_sama5d3.rst b/doc/hardware_v7a_noneon_sama5d3.rst new file mode 100644 index 0000000..aaeed3e --- /dev/null +++ b/doc/hardware_v7a_noneon_sama5d3.rst @@ -0,0 +1,22 @@ +SAMA5D3 boards +============== + +Supported boards: + + * EVB-KSZ9477 (with ATSAMA5D36A) + Image: platform-v7a_noneon/images/image-ksz9477-evb.hdimg + +Boot Media +---------- + +DistroKit generates ``platform-v7a_noneon/images/*.hdimg``. +Use the respective image for your board and write it to your SD card. + +The EVB-KSZ9477 board has only 1 SD slot. To boot from SD, J13 (NAND Enable) +jumper should be removed. + +Serial Console +-------------- + +The EVB-KSZ9477 has an J10 Serial Comm interface. All UART related pins are +properly named. diff --git a/doc/hardware_v7a_qemu.rst b/doc/hardware_v7a_qemu.rst index 996323e..c993f88 100644 --- a/doc/hardware_v7a_qemu.rst +++ b/doc/hardware_v7a_qemu.rst @@ -4,7 +4,7 @@ QEmu The v7a platform is ready to run in qemu, using the versatile express hardware simulation. -There are two ways to run DistoKit inside qemu: +There are two ways to run DistroKit inside qemu: * With barebox: Run ``./configs/platform-v7a/run barebox`` to boot the current image with barebox. diff --git a/doc/hardware_v7a_raspi2.rst b/doc/hardware_v7a_raspi2.rst deleted file mode 100644 index a8cdb06..0000000 --- a/doc/hardware_v7a_raspi2.rst +++ /dev/null @@ -1,15 +0,0 @@ -Raspberry Pi 2 -============== - -Boot Media ----------- -Use the image ``platform-v7a/images/rpi2.hdimg`` and copy it onto your MicroSD-Card. - -Serial Console --------------- -The serial boot console is available at J8 (the GPIO header) with 115200 Baud and 8N1 on the following Pins: - -* J8.6: GND -* J8.8: Tx -* J8.10: Rx - diff --git a/doc/hardware_v7a_raspi3.rst b/doc/hardware_v7a_raspi23.rst index a4069c2..f1d2041 100644 --- a/doc/hardware_v7a_raspi3.rst +++ b/doc/hardware_v7a_raspi23.rst @@ -1,9 +1,24 @@ +Raspberry Pi 2 +============== + +Boot Media +---------- +Use the same ``platform-v7a/images/rpi.hdimg`` image and write it to your MicroSD-Card. + +Serial Console +-------------- +The serial boot console is available at J8 (the GPIO header) with 115200 Baud and 8N1 on the following Pins: + +* J8.6: GND +* J8.8: Tx +* J8.10: Rx + Raspberry Pi 3 ============== Boot Media ---------- -Use the image ``platform-v7a/images/rpi3.hdimg`` and copy it onto your MicroSD-Card. +Use the same ``platform-v7a/images/rpi.hdimg`` image and write it to your MicroSD-Card. Serial Console -------------- @@ -18,10 +33,10 @@ Raspberry Pi Compute Module 3+ Boot Media ---------- -Use the image ``platform-v7a/images/rpicm3.hdimg`` and copy it onto your MicroSD-Card. +Use the same ``platform-v7a/images/rpi.hdimg`` image and write it to your MicroSD-Card. If you have a hardware with eMMC the uSD slot is not functional, in this case -you have to use `usbboot <https://github.com/raspberrypi/usbboot`_ to switch +you have to use `usbboot <https://github.com/raspberrypi/usbboot>`_ to switch the hardware into USB mass storage mode. See their documentation and `"Flashing the Compute Module eMMC" at raspberrypi.org <https://www.raspberrypi.org/documentation/hardware/computemodule/cm-emmc-flashing.md>` diff --git a/doc/hardware_v7a_riot.rst b/doc/hardware_v7a_riot.rst index 0ea4ce7..a6e2365 100644 --- a/doc/hardware_v7a_riot.rst +++ b/doc/hardware_v7a_riot.rst @@ -3,7 +3,7 @@ RIoT-Board Boot Media ---------- -Use the image ``platform-v7a/images/riotboard.hdimg`` and copy it onto your SD card. +Use the image ``platform-v7a/images/riotboard.hdimg`` and write it to your SD card. Set the DIP switches (SW1) accordingly to boot from a full-size SD card (J6 on the bottom) or a Micro SD card (J7 on top): @@ -24,3 +24,69 @@ The serial boot console is available at the debug-header J18 at 115200 Baud and * J18.2: RxD * J18.3: GND +Fast development +---------------- + +For development the RIoT-Board bootloader supports 'fastboot'. Refer +:ref:`fast_development` for Linux and BSP preparation on demand. + +RIoT i.MX6S +~~~~~~~~~~~ + +The BSP already supports 'fastboot' and prepares the target accordingly. +The PARTITION names might differ, so you should check first, what PARTITIONs +are exported. + +To get the exported PARTITION names, available via 'fastboot', you can run:: + + $ fastboot getvar all + (bootloader) version: 0.4 + (bootloader) bootloader-version: barebox-2023.02.1 + (bootloader) max-download-size: 8388608 + (bootloader) partition-size:mmc1: 00000000 + (bootloader) partition-type:mmc1: unavailable + (bootloader) partition-size:mmc2: 00000000 + (bootloader) partition-type:mmc2: unavailable + (bootloader) partition-size:mmc3: e5000000 + (bootloader) partition-type:mmc3: basic + (bootloader) partition-size:ram-kernel: 00000000 + (bootloader) partition-type:ram-kernel: file + (bootloader) partition-size:ram-initramfs: 00000000 + (bootloader) partition-type:ram-initramfs: file + (bootloader) partition-size:ram-oftree: 00000000 + (bootloader) partition-type:ram-oftree: file + (bootloader) partition-size:bbu-emmc: 000e0000 + (bootloader) partition-type:bbu-emmc: basic + +In this example, the PARTITION names are 'mmc1', 'mmc2', 'mmc3', 'ram-kernel', +'ram-initramfs', 'ram-oftree' and 'bbu-emmc'. In this example the two possible +SD cards are not plugged in (e.g. "unavailable"). + +.. note:: You need to restart the fastboot usbgadget, if you probe the SD cards + later on. + +Just connect the USB OTG connector to your host and run:: + + $ fastboot flash ram-kernel platform-v7a/images/linuximage -S 1 + $ fastboot flash ram-oftree platform-v7a/images/imx6dl-riotboard.dtb -S 1 + $ fastboot flash ram-initramfs platform-v7a/images/root.cpio.gz -S 1 + $ fastboot oem exec -- boot ram-fastboot + +You can populate local memory like the eMMC as well. But only full memory +devices and no particular partitions. + +If inserted, the regular SD card:: + + $ fastboot flash mmc1 platform-v7a/images/riotboard.hdimg -S 1 + +If inserted, the µSD card:: + + $ fastboot flash mmc2 platform-v7a/images/riotboard.hdimg -S 1 + +The built-in eMMC:: + + $ fastboot flash mmc3 platform-v7a/images/riotboard.hdimg -S 1 + +.. note:: If you have no USB connection to the RIoT i.MX6S, you can use + a network connection instead. Just run all the 'fastboot' commands + shown above with the additional option '-s udp:<RIoT i.MX6S IP address>'. diff --git a/doc/hardware_v7a_sama5d2.rst b/doc/hardware_v7a_sama5d2.rst index ae39cdf..083a46d 100644 --- a/doc/hardware_v7a_sama5d2.rst +++ b/doc/hardware_v7a_sama5d2.rst @@ -10,7 +10,7 @@ Boot Media ---------- DistroKit generates ``platform-v7a/images/sama5d27-*.hdimg``. -Use the respective image for your board and copy it onto your SD card. +Use the respective image for your board and write it to your SD card. The Giant board has only 1 microSD slot, the EK has additionally 1 normal SD-sized slot. Both can be used. diff --git a/doc/hardware_v7a_sama5d4.rst b/doc/hardware_v7a_sama5d4.rst new file mode 100644 index 0000000..6d371b0 --- /dev/null +++ b/doc/hardware_v7a_sama5d4.rst @@ -0,0 +1,16 @@ +SAMA5D4 boards +============== + +DistroKit currently supports one SAMA5D4 board: + + * Wifx L1 LoRaWAN Gateway + + +Boot Media +---------- + +The L1 will boot from a bootable SD-Card if one is inserted and otherwise +fall back to booting from NAND flash. DistroKit generates only a SD-Card +image for now: + + * ``platform-v7a/images/wifx-l1-sd.hdimg``. diff --git a/doc/hardware_v7a_udoo_neo.rst b/doc/hardware_v7a_udoo_neo.rst index b84fde7..674bdfe 100644 --- a/doc/hardware_v7a_udoo_neo.rst +++ b/doc/hardware_v7a_udoo_neo.rst @@ -4,7 +4,7 @@ Udoo Neo Boot Media ---------- -Use the image ``platform-v7a/images/udoo-neo.hdimg`` and copy it onto your MicroSD-Card. +Use the image ``platform-v7a/images/udoo-neo.hdimg`` and write it to your MicroSD-Card. Serial Console diff --git a/doc/hardware_v8a_espressobin.rst b/doc/hardware_v8a_espressobin.rst index 63d3e89..dc4fc77 100644 --- a/doc/hardware_v8a_espressobin.rst +++ b/doc/hardware_v8a_espressobin.rst @@ -3,7 +3,7 @@ Marvell espressobin Boot Media ---------- -Use the image ``platform-v8a/images/espressobin.hdimg`` and copy it onto your MicroSD-Card, e.g: +Use the image ``platform-v8a/images/espressobin.hdimg`` and write it to your MicroSD-Card, e.g: .. code-block:: shell diff --git a/doc/hardware_v8a_rock3a.rst b/doc/hardware_v8a_rock3a.rst new file mode 100644 index 0000000..72bf187 --- /dev/null +++ b/doc/hardware_v8a_rock3a.rst @@ -0,0 +1,36 @@ +Radxa Rock 3 Model A +==================== + +Boot Media +---------- + +Write the image ``platform-v8a/images/rock3a.img`` to a microSD card. Put the +microSD card into the Rock 3A and boot it, the system will autoboot to linux. + +If you just want to boot to barebox instead of a full linux image from microSD card +(e.g. for chainloading or tftpboot), +write the image ``platform-v8a/images/barebox-rock3a.norimg`` to a microSD card instead. + +Alternatively, you may put the Rock 3A into MASKROM mode following the `Rock 3 +Hardware User Manual <https://wiki.radxa.com/Rock3/hardware/3a>`_ and boot +Barebox via USB: + +.. code-block:: shell + + platform-v8a/sysroot-host/bin/rk-usb-loader platform-v8a/images/barebox-rock3a.img + +Once Barebox is booted, write the image ``platform-v8a/images/rock3a.img`` via +tftp or NFS to the eMMC to persist it. Disable MASKROM mode and reboot the +board to start from eMMC. + +Once booted to linux, you can write ``platform-v8a/images/barebox-rock3a.norimg`` using mtd-utils +to the NOR flash, which can then be used as fallback boot source whenever booting from microSD +card or eMMC fails. + +Serial Console +-------------- + +The serial boot console is available via the pin +header of the board. Follow the `Rock 3 Development Guide +<https://wiki.radxa.com/Rock3/dev/serial-console>`_ for connecting an USB to +TTL serial cable. Make sure the cable support 1.5 Mbps. diff --git a/doc/hardware_x86_64_qemu.rst b/doc/hardware_x86_64_qemu.rst index f3dfd77..e64c23c 100644 --- a/doc/hardware_x86_64_qemu.rst +++ b/doc/hardware_x86_64_qemu.rst @@ -3,4 +3,4 @@ QEMU The x86_64 platform is ready to run in qemu, using the pc-q35-2.12 KVM simulation. -To run DistoKit inside qemu, execute ``./configs/platform-x86_64/run``. +To run DistroKit inside qemu, execute ``./configs/platform-x86_64/run``. diff --git a/doc/index.rst b/doc/index-layer-1-distrokit.rst index 2ce9c75..751ef3f 100644 --- a/doc/index.rst +++ b/doc/index-layer-1-distrokit.rst @@ -3,12 +3,11 @@ Welcome to DistroKit .. toctree:: :glob: - :numbered: :maxdepth: 2 intro hardware - guru + testing * :ref:`search` * :ref:`genindex` diff --git a/doc/intro.rst b/doc/intro.rst index 86db137..d07a238 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -81,6 +81,13 @@ using `git format-patch <https://git-scm.com/docs/git-format-patch>`_ on the DistroKit git repository (also see its man page for info on using mailers other than *git send-email*). +Mails sent to the DistroKit mailing list are archived on ``lore.distrokit.org``. +Patch series can be fetched with `b4 <https://pypi.org/project/b4/>`_ :: + + git config b4.midmask https://lore.distrokit.org/%s + git config b4.linkmask https://lore.distrokit.org/%s + b4 am https://lore.distrokit.org/$messageid # replace with link + DistroKit uses the `Developer’s Certificate of Origin <https://developercertificate.org/>`_:: By making a contribution to this project, I certify that: @@ -109,11 +116,30 @@ using your real name (sorry, no pseudonyms or anonymous contributions) to the end of your commit message, or if you use Git, make your commit with ``git commit --signoff``. +Maintenance scripts +~~~~~~~~~~~~~~~~~~~ + +Before sending your patch, you should run ``ptxdist lint`` and check its output. +Your patch should not add any new lint errors. + +For migrating PTXdist to a new version, there is the wrapper script +``scripts/p-all`` that runs PTXdist with the supplied arguments on all existing +platforms in DistroKit, for example:: + + $ ./scripts/p-all migrate + +The *mips* and *v7a* platforms use config diffs for kernel and/or barebox packages. +When touching their config files, you can use ``scripts/update-diffs-mips.sh`` and +``scripts/update-diffs-v7a.sh`` respectively to update the config diffs. + License ------- Copyright (C) 2020 Pengutronix and individual contributors DistroKit is licensed under the GNU General Public License, version 2.0. -See the file named LICENSE in the root directory of this project for the full -license terms, and the version control history for contributor information. +See the file named `LICENSE`_ in the root directory of this project for the full +license terms, and the `version control history`_ for contributor information. + +.. _LICENSE: https://git.pengutronix.de/cgit/DistroKit/tree/LICENSE +.. _version control history: https://git.pengutronix.de/cgit/DistroKit/log diff --git a/doc/testing.rst b/doc/testing.rst new file mode 100644 index 0000000..ef477cb --- /dev/null +++ b/doc/testing.rst @@ -0,0 +1,165 @@ +.. _fast_development: + +Fast development +================ + +Sometimes a quick test should be done: a new kernel feature or a tool +should be tested on a real target. + +If the target suports USB OTG (or peripheral mode) or network, 'fastboot' +can be an easy-to-use solution. + +'fastboot' support +------------------ + +For a fast development or testing cycle you can use 'fastboot' via +USB or network to transfer the required parts to the target system. + +Here we want to run a Linux kernel and a corresponding root filesystem, +without writing target system local memories again and again for each +development or test cycle. + +In this test, we transfer the required files to the target system +which only needs to run a 'fastboot' capable bootloader. + +Since we want to use an initramfs as the kernel's root filesystem, we +have some requirements to the target system's free memory. The bootloader +keeps up to 512 MiB of memory to add files to its own RAM disk. The +512 MiB is valid for a physical memory size of 1 GiB and above. With less +physical memory it is always 50 % of the available physical memory. +Keep an eye on the size of the initramfs file if it fits onto the +bootloader's RAM disk. Reduce its size on demand. + +Note: the 50 % rule is only valid for the time the bootloader runs. After + starting the Linux kernel, 100 % of the physical memory is available. + +Some settings are required to make it work smoothly. + +Linux kernel +------------ + +- CONFIG_BLK_DEV_INITRD=y + +And one of the supported decompressors: + +- CONFIG_RD_GZIP + +Note: the required decompressor depends on the used compression method for the + initramfs selected in the BSP. See below. + +Bootloader +---------- + +The 'bootm' command must support initrd/initramfs: + +- CONFIG_BOOTM_INITRD = y + +If your target system has an OTG connector, you should enable 'fastboot' on +the gadget interface: + +- CONFIG_USB_GADGET = y +- CONFIG_USB_GADGET_FASTBOOT = y +- CONFIG_CMD_USBGADGET = y + +If you want to use 'fastboot' via network instead (or in addition) to the +USB interface, you should enable this channel as well: + +- CONFIG_NET_FASTBOOT = y + +Since we want to transfer large initrd/initramfs files, 'fastboot' requires +'sparse' feature support: + +- CONFIG_FASTBOOT_SPARSE = y + +And we want run the downloaded files, so we need: + +- CONFIG_FASTBOOT_CMD_OEM = y + +BSP +--- + +Create an initramf of the root filesystem: + +- PTXCONF_IMAGE_ROOT_CPIO = y + +You need to select a compression method for the initramfs file in relation to +the selected decompression support in the Linux kernel. See notes above. + +- PTXCONF_IMAGE_ROOT_CPIO_COMPRESSION_MODE_GZ = y + +The generic behaviour changes when the Linux kernel starts an initrd/initramfs +and it tries to start '/init' instead of an init processes in subdirectories. +If you can change the kernel's command line, you can restore the generic behaviour +by adding 'rdinit=/sbin/init'. If not, you can create a softlink at '/init' pointing +to '/sbin/init via: + +- PTXCONF_ROOTFS_INIT_LINK + +Optimisation +------------ + +Some BPS settings do not make sense regarding used in an initramfs instead +of a persistent target system local memory. For development or testing some +settings should be changed, to reduce the file sizes and boot time. + +The Linux kernel will be transferred separately, so it makes less sense to +have it in the root filesystem as well. This will reduce the size of the +initramfs. + +- PTXCONF_KERNEL_INSTALL = n + +Some 'rc-once' jobs are useless in an initramfs and only increase the +boot time again and again: + +- PTXCONF_GLIBC_LDCONFIG_RC_ONCE = n +- PTXCONF_MACHINE_ID_RC_ONCE = n + +If possible, disable the whole rc-once step: + +- PTXCONF_RC_ONCE = n + +If you don't need ssh, you can disable its key generation as well: + +- PTXCONF_OPENSSH_SSHD_GENKEYS = n + +Preparations +------------ + +'fastboot' requires to divide large files into smaller chunks, if their +size hits some threshold. In this case, there are some additional requirements +to the size of the file itself: its size must be a multiple of 4 kiB. + +Note: if this additional requirement isn't met, the error message is + misleading and states about an 'invalid value' after the first + transfer. + +Most of the time the initramfs file hits the threshold. Thus, it must +be 4 kiB aligned:: + + dd if=<platform-dir>/images/root.cpio.gz of=cpio.gz conv=sync bs=4096 + +Target +------ + +Enable the 'fastboot' feature on the target system:: + + usbgadget -a -A /kernel(kernel)c,/devicetree(devicetree)c,/initrd(initrd)c + +Host +---- + +Download the three parts into the target system:: + + fastboot -i 7531 flash kernel <platform-dir>/images/linuximage + fastboot -i 7531 flash devicetree <platform-dir>/images/<devicetree> + fastboot -i 7531 flash initrd cpio.gz + +If you have no '/init' in your root filesystem, you need to define the +init executable to be run by the Linux kernel:: + + fastboot -i 7531 oem exec 'global linux.bootargs.ramfs=rdinit=/sbin/init' + +In the final step, just start the already downloaded files:: + + fastboot -i 7531 oem exec -- bootm -o /devicetree -r /initrd /kernel + |