diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/boards/openrisc.rst | 2 | ||||
| -rw-r--r-- | Documentation/devel/devel.rst | 1 | ||||
| -rw-r--r-- | Documentation/devel/project-ideas.rst | 174 | ||||
| -rw-r--r-- | Documentation/devicetree/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/talks.rst | 130 | ||||
| -rw-r--r-- | Documentation/user/barebox.rst | 1 | ||||
| -rw-r--r-- | Documentation/user/introduction.rst | 15 | ||||
| -rw-r--r-- | Documentation/user/watchdog.rst | 11 |
9 files changed, 333 insertions, 3 deletions
diff --git a/Documentation/boards/openrisc.rst b/Documentation/boards/openrisc.rst index 34586b4a76..17b0aef4a6 100644 --- a/Documentation/boards/openrisc.rst +++ b/Documentation/boards/openrisc.rst @@ -22,7 +22,7 @@ Example of downloading and installing a toolchain:: $ export PATH=$PATH:$PWD/or1k-elf/bin Running OpenRISC barebox on qemu ------------------------------- +-------------------------------- Running barebox on qemu is similar to running linux on qemu see more details on the qemu wiki site at https://wiki.qemu.org/Documentation/Platforms/OpenRISC diff --git a/Documentation/devel/devel.rst b/Documentation/devel/devel.rst index f703c3bf27..39070074ca 100644 --- a/Documentation/devel/devel.rst +++ b/Documentation/devel/devel.rst @@ -10,6 +10,7 @@ Contents: porting background-execution + project-ideas * :ref:`search` * :ref:`genindex` diff --git a/Documentation/devel/project-ideas.rst b/Documentation/devel/project-ideas.rst new file mode 100644 index 0000000000..f27e4d5406 --- /dev/null +++ b/Documentation/devel/project-ideas.rst @@ -0,0 +1,174 @@ +##################### +barebox Project Ideas +##################### + +This section collects ideas to improve barebox and should serve as a pool +of ideas for people who want to enter the field of firmware development +but need some guidance what to work on. + +These tasks can be adopted as part of programs like Google Summer of Code +or by motivated individuals outside such programs. + +If you find a project interesting and would like to work on it, reach out +to the :ref:`mailing list <feedback>` and we can together +try to figure out whether you are a good match for the project. + +This list can be edited and extended by sending patches to the mailing list. +Other interesting ideas: Support for new file systems (EROFS, extfat, btrfs). +Switch device framework (currently scripts write into a ``/dev/switch`` file +to configure passthrough), Improvements for barebox-efi (e.g. as a coreboot +payload), ... etc. + +Address static analyzer feedback for barebox +============================================ + +Skills: C + +barebox is automatically tested using Synopsys' free "Coverity Scan" service. +The static analyzer has so far identified 191 possible defects at +https://scan.coverity.com/projects/barebox + +There is a number of false positives there, but it already helped us +find actual regressions, e.g. 610720857348 ("fs: ext4: fix bogus behavior +on failure to read ext4 block"). + +To make this service more useful, the project would involve categorizing +reported issues and handling them as appropriate: Mark them as not applicable +if false positive or provide patches to fix real issues. + +This project does not require dedicated hardware. QEMU or barebox built +to run under Linux (sandbox) may be used. + +Update barebox networking stack for IPv6 support +================================================ + +Skills: C, Networking + +The barebox network stack is mainly used for TFTP and NFSv3 (over UDP) boot. +Most embedded systems barebox runs on aren't deployed to IPv6 networks yet, +so it's the right time now to future-proof and learn more about networking +internals. One major complication with IPv6 support is neighbor discovery +protocols that require networking to be possible "in the background". +barebox' recent improvements of resource sharing and cooperative scheduling +makes it possible to integrate an IPv6 stack, e.g. lwIP. + +There are also community patches to integrate a TCP stack into barebox. +These can be evaluated as time allows. + +This project does not require dedicated hardware. QEMU or barebox built +to run under Linux (sandbox) may be used. + +Improving barebox test coverage +=============================== + +Skills: C + +barebox is normally tested end-to-end as part of a deployed system. +More selftests/emulated tests would reduce the round trip time for testing +and thus enable more widely tested patches. A framework has been recently +merged to enable this: + + * Selftest similar to the kernel can be registered and run. These + directly interface with C-Code. + * Labgrid tests: These boot barebox in a virtual machine or on real + hardware and use the shell to test barebox behaviors. + +This project will focus on improving the testing coverage by writing more +tests for barebox functionality and by fuzzing the parsers available in +barebox, with special consideration to the FIT parser, which is used in +secure booting setups. + +This project does not require dedicated hardware. QEMU or barebox built +to run under Linux (sandbox) may be used. + +Porting barebox to new hardware +=============================== + +Skills: C, low-level affinity + +While Linux and Linux userspace can be quite generic with respect to the +hardware it runs on, the bucket needs to stop somewhere: barebox needs +detailed knowledge of the hardware to initialize it and to pass this +along information to Linux. In this project, familiarity with barebox +and a new unsupported SoC will be established with the goal of porting +barebox to run on it. Prospective developers can suggest suitable +hardware (boards/SoCs) they are interested in. Preference is for +hardware, which is generally available and has more open documentation. + +The goal is to have enough support to run barebox on the board, set up +RAM and load a kernel from non-volatile storage and boot it. + +If time allows (because most drivers are already available in barebox), +new drivers can be ported to enable not only running Linux on the board, +but bareDOOM as well. + +This project requires embedded hardware with preferably an ARM SoC, as +these have the widest barebox support, but other architectures are ok +as well. + +Improve barebox RISC-V support +============================== + +Skills: C, RISC-V interest, low-level affinity + +barebox supports a number of both soft and hardRISC-V targets, +e.g.: BeagleV, HiFive, LiteX and the QEMU/TinyEMU Virt machine. + +Unlike e.g. ARM and MIPS, RISC-V support is still in its formative +stage, so much opportunity in implementing the gritty details: + + - Physical memory protection in M-Mode to trap access violations + - MMU support in S-Mode to trap access violations + - Improve barebox support for multiple harts (hardware threads) + +This project does not require dedicated hardware. QEMU can be used. + +Improve barebox I/O performance +=============================== + +Skills: C, low-level affinity + +On a normal modern system, booting may involve mounting and traversing +a file system, which employs caching for directory entries and sits +on top of a block device which caches blocks previously read from the +hardware driver, often by means of DMA. There are a number of improvements +possible to increase throughput of barebox I/O: + + - Support for higher MMC speed modes: The maximum currently supported + is 50/52 MHz and no DDR. + - More efficient erase: Communication protocols like Android Fastboot + encode large blocks of zeros specially. MMCs with erase-to-zero + capability could perform such erases in the background instead + of having to write big chunks of zeros. + - Block layer block sizes: There is a fixed block size used for + caching, which is meant to be a good compromise for read + and write performance. This may not be optimal for all devices + and can be revisited. + +This project requires embedded hardware with SD/eMMC that is supported +by a barebox media card interface (MCI) driver. + +Improve JSBarebox, the barebox web demo +======================================= + +Skills: C (Basics), Javascript/Web-assembly, Browser-Profiling + +While Linux and Linux userspace can be quite generic with respect to the +hardware it runs on, the bucket needs to stop somewhere: barebox needs +detailed knowledge of the hardware to initialize it and to pass this +along information to Linux. JSBarebox removes the hurdle of porting +barebox to a new board, for new users who are only interested in +trying it out: The browser runs Tinyemu, a virtual machine in which +barebox executes as if on real hardware and the user can manipulate the +(virtual) hardware from the barebox shell and learn about barebox +conveniences: barebox.org/jsbarebox/ + +The project is about streamlining this demo: CPU usage currently is +quite high and teaching barebox to idle the CPU (as we do on sandbox) +didn't help. This needs to be analyzed with the profiling tools +provided with modern browsers. The remainder of the project can then +focus on improving the jsbarebox tutorial. e.g. by adding new +peripherals to the virtual machine. + +This project does not require dedicated hardware. The development +machine need only support a recent browser. diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index 198c4893ff..d03db3cf82 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -114,4 +114,5 @@ Contents: bindings/leds/* bindings/misc/* bindings/mtd/* + bindings/regulator/* bindings/rtc/* diff --git a/Documentation/index.rst b/Documentation/index.rst index 836dc41af2..a3e019e9f0 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -20,6 +20,7 @@ Contents: glossary devicetree/* devel/devel.rst + talks * :ref:`search` * :ref:`genindex` diff --git a/Documentation/talks.rst b/Documentation/talks.rst new file mode 100644 index 0000000000..5f1af59931 --- /dev/null +++ b/Documentation/talks.rst @@ -0,0 +1,130 @@ +Talks and Lectures +================== + +This is a collection of talks held about barebox use and development +at different technical conferences. The most recent overview talk +is from 2020: + +Beyond 'Just' Booting: Barebox Bells and Whistles +------------------------------------------------- + +Ahmad Fatoum, Embedded Linux Conference - Europe 2020 +`[slides] <https://elinux.org/images/9/9d/Barebox-bells-n-whistles.pdf>`__ +`[video] <https://www.youtube.com/watch?v=fru1n54s2W4>`__ + + Porting barebox to a new STM32MP1 board and a general discussion + of design choices like multi-image, VFS, POSIX/Linux API, + fail-safe updates, boot fall-back mechanisms, etc. + +Besides older overview talks, there's a number of talks held +about different aspects of barebox use. +These are listed here in reverse chronological order. + +DOOM portieren für Einsteiger - Heavy Metal auf Bare Metal (German) +------------------------------------------------------------------- + +Ahmad Fatoum, FrOSCon 2021 +`[slides] <https://programm.froscon.de/2021/system/event_attachments/attachments/000/000/622/original/heavy-metal-on-bare-metal.pdf>`__ +`[video] <https://media.ccc.de/v/froscon2021-2687-doom_portieren_fur_einsteiger>`__ + + "DOOM as a boot splash. How, why and how to get it on your nearest + home appliance". A (German) walkthrough on how to leverage barebox + APIs to run DOOM on any hardware supported by barebox. + +Initializing RISC-V: A Guided Tour for ARM Developers +----------------------------------------------------- + +Rouven Czerwinski & Ahmad Fatoum, Embedded Linux Conference 2021 +`[slides] <https://elinux.org/images/8/80/Initializing-riscv.pdf>`__ +`[video] <https://www.youtube.com/watch?v=70oYYuflFLs>`__ + + A guide through the RISC-V architecture and some of its ISA extensions + and a walkthrough of the barebox port to the Beagle-V Starlight. + +From Reset Vector to Kernel - Navigating the ARM Matryoshka +----------------------------------------------------------- + +Ahmad Fatoum, FOSDEM 2021 +`[slides & video] <https://archive.fosdem.org/2021/schedule/event/from_reset_vector_to_kernel/>`__ + + A walkthrough of NXP i.MX8M bootstrap. From Boot ROM through barebox to Linux. + +Booting your i.MX processor secure and implementing i.MX8 secure boot in barebox +-------------------------------------------------------------------------------- + +Rouven Czerwinski, `Stratum 0 Talk 2019 <https://stratum0.org/wiki/Vortr%C3%A4ge/Vorbei#2019>`__ +`[video] <https://www.youtube.com/watch?v=ZUGLEulZLWM>`__ + + A walkthrough of NXP i.MX8MQ high assurance boot with barebox. + +Porting Barebox to the Digi CC-MX6UL SBC Pro (German) +----------------------------------------------------- + +Rouven Czerwinski, `Stratum 0 Live-Hacking 2019 <https://stratum0.org/wiki/Vortr%C3%A4ge/Vorbei#2019>`__ +`[video] <https://www.youtube.com/watch?v=FIwF6GfmsWM>`__ + + Live-coding a barebox port to a new i.MX6UL board while + explaining the details (in German). + +Remote update adventures with RAUC, Yocto and Barebox +----------------------------------------------------- + +Patrick Boettcher, `Embedded Recipes 2019 <https://embedded-recipes.org/2019/remote-update-adventures-with-rauc-yocto-and-barebox/>`__ +`[video] <https://www.youtube.com/watch?v=hS3Fjf7fuHM>`__ + + Remote update and redundant boot of Embedded Linux devices + in the field with RAUC and barebox bootchooser. + +Verified Boot: From ROM to Userspace +------------------------------------ + +Marc Kleine-Budde, Embedded Linux Conference - Europe 2016 +`[slides] <https://elinux.org/images/f/f8/Verified_Boot.pdf>`__ +`[video] <https://www.youtube.com/watch?v=lkFKtCh2SaU>`__ + + Using FOSS components, including barebox, for a cryptographically + secured boot chain on NXP i.MX6 SoCs. + +Booting Linux Made Easy: A Barebox Update +----------------------------------------- + +Robert Schwebel, `FOSDEM 2014 <https://archive.fosdem.org/2014/schedule/event/_booting_linux_made_easy:_a_barebox_update/>`__ +`[video] <https://www.youtube.com/watch?v=p-mHAQaJQcM>`__ + + An overview talk on barebox use in embedded Linux systems. + +Barebox and Bootloader Specification +------------------------------------ + +Sascha Hauer, Embedded Linux Conference - Europe 2013 +`[slides] <https://elinux.org/images/9/90/Barebox-elce2013-bootloaderspec.pdf>`__ +`[video] <https://www.youtube.com/watch?v=Z8FcIGXox_Y>`__ + + The freedesktop.org bootloader specification and its support in barebox. + +Barebox Bootloader +------------------ + +Sascha Hauer, Embedded Linux Conference - Europe 2012 +`[slides] <https://elinux.org/images/6/6b/PRE-20121108-1-Barebox.pdf>`__ +`[video] <https://www.youtube.com/watch?v=oY8BjCEt_p8>`__ + + An update on barebox development progress with a discussion of newly + implemented features in the preceding three years. + +Barebox: Booting Linux Fast and Fancy +------------------------------------- + +Robert Schwebel & Sascha Hauer, Embedded Linux Conference - Europe 2010 +`[slides] <https://elinux.org/images/8/89/ELCE-2010-Barebox-Booting-Linux-Fast-and-Fancy.pdf>`__ + + Boot time optimization while using barebox. + +U-Boot-v2 +--------- + +Sascha Hauer & Marc Kleine-Budde, Embedded Linux Conference 2009 +`[slides] <https://elinux.org/images/9/90/Hauer-U_BootV2.pdf>`__ + + Early barebox (still named U-Boot v2 back then) presentation on + the motivation for the fork and the niceties made possible by it. diff --git a/Documentation/user/barebox.rst b/Documentation/user/barebox.rst index a890aa4dbe..7b37ddba77 100644 --- a/Documentation/user/barebox.rst +++ b/Documentation/user/barebox.rst @@ -222,6 +222,7 @@ command doesn't support the barebox binaries directly, they first have to be converted to uImage format using the mkimage tool provided with U-Boot: .. code-block:: console + sh: mkimage -n barebox -A arm -T kernel -C none -a 0x80000000 -d \ build/images/barebox-freescale-imx53-loco.img image diff --git a/Documentation/user/introduction.rst b/Documentation/user/introduction.rst index 8a980a70ab..e7388b8bc9 100644 --- a/Documentation/user/introduction.rst +++ b/Documentation/user/introduction.rst @@ -15,6 +15,8 @@ development binary as well as for lean production systems. Just like busybox is the Swiss Army Knife for embedded Linux, barebox is the Swiss Army Knife for bare metal, hence the name. +.. _feedback: + Feedback -------- @@ -24,6 +26,15 @@ discussion of barebox takes place here: http://lists.infradead.org/mailman/listinfo/barebox/ -There's also an IRC channel: +Mails sent to the barebox mailing list are archived on +`lore.barebox.org <https://lore.barebox.org/barebox/>`_. + +Patch series sent there can be fetched with `b4 <https://pypi.org/project/b4/>`_ :: + + git config b4.midmask https://lore.barebox.org/%s + git config b4.linkmask https://lore.barebox.org/%s + b4 am https://lore.barebox.org/$messageid # replace with link -IRC: #barebox (Freenode) +There's also an IRC channel, which is +`bridged to Matrix <https://app.element.io/#/room/#barebox:matrix.org>`_: +#barebox on Libera Chat diff --git a/Documentation/user/watchdog.rst b/Documentation/user/watchdog.rst index ff400317a0..0220965598 100644 --- a/Documentation/user/watchdog.rst +++ b/Documentation/user/watchdog.rst @@ -10,6 +10,15 @@ the bootloader. For these scenarios barebox provides the watchdog framework with the following functionality and at least ``CONFIG_WATCHDOG`` should be enabled. +Disabling for development +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The shorthand command ``wd -x`` will disable all watchdogs. +If hardware (or driver) doesn't support turning off the watchdog, +an autpoller will be registered to periodically feed watchdogs. +This should only be needed for development. +See :ref:`boot-watchdog-timeout` for how to use the watchdog in the field. + Polling ~~~~~~~ @@ -98,6 +107,8 @@ device tree or via the ``priority`` device parameter. Normally, watchdogs that have a wider effect should be given the higher priority (e.g. PMIC watchdog resetting the board vs. SoC's watchdog resetting only itself). +.. _boot-watchdog-timeout: + Boot Watchdog Timeout ~~~~~~~~~~~~~~~~~~~~~ |