In preparation for adding a debugging chapter, move the parts in the porting guide that are equally applicable to debugging to its separate file, so they can be referenced easily.
Signed-off-by: Ahmad Fatoum <a.fat...@pengutronix.de> --- Documentation/devel/architecture.rst | 78 ++++++++++++++++++++++++++ Documentation/devel/porting.rst | 83 +++------------------------- 2 files changed, 85 insertions(+), 76 deletions(-) create mode 100644 Documentation/devel/architecture.rst diff --git a/Documentation/devel/architecture.rst b/Documentation/devel/architecture.rst new file mode 100644 index 000000000000..83556095098a --- /dev/null +++ b/Documentation/devel/architecture.rst @@ -0,0 +1,78 @@ +.. _architecture: + +#################### +barebox architecture +#################### + +The usual barebox binary consists of two parts. A prebootloader doing +the bare minimum initialization and then the proper barebox binary. + +barebox proper +============== + +This is the main part of barebox and, like a multi-platform Linux kernel, +is platform-agnostic: The program starts, registers its drivers and tries +to match the drivers with the devices it discovers at runtime. +It initializes file systems and common management facilities and finally +starts an init process. barebox knows no privilege separation and the +init process is built into barebox. +The default init is the :ref:`Hush`, but can be overridden if required. + +For such a platform-agnostic program to work, it must receive external +input about what kind of devices are available: For example, is there a +timer? At what address and how often does it tick? For most barebox +architectures this hardware description is provided in the form +of a flattened device tree (FDT). As part of barebox' initialization +procedure, it unflattens (parses) the device tree and starts probing +(matching) the devices described within with the drivers that are being +registered. + +The device tree can also describe the RAM available in the system. As +walking the device tree itself consumes RAM, barebox proper needs to +be passed information about an initial memory region for use as stack +and for dynamic allocations. When barebox has probed the memory banks, +the whole memory will become available. + +As result of this design, the same barebox proper binary can be reused for +many different boards. Unlike Linux, which can expect a bootloader to pass +it the device tree, barebox *is* the bootloader. For this reason, barebox +proper is prefixed with what is called a prebootloader (PBL). The PBL +handles the low-level details that need to happen before invoking barebox +proper. + +Prebootloader (PBL) +=================== + +The :ref:`prebootloader <pbl>` is a small chunk of code whose objective is +to prepare the environment for barebox proper to execute. This means: + + - Setting up a stack + - Determining a memory region for initial allocations + - Provide the device tree + - Jump to barebox proper + +The prebootloader often runs from a constrained medium like a small +(tens of KiB) on-chip SRAM or sometimes even directly from flash. + +If the size constraints allow, the PBL will contain the barebox proper +binary in compressed form. After ensuring any external DRAM can be +addressed, it will unpack barebox proper there and call it with the +necessary arguments: an initial memory region and the FDT. + +If this is not feasible, the PBL will contain drivers to chain load +barebox proper from the storage medium. As this is usually the same +storage medium the PBL itself was loaded from, shortcuts can often +be taken: e.g. a SD-Card could already be in the correct mode, so the +PBL driver can just read the blocks without having to reinitialize +the SD-card. + +barebox images +============== + +In a typical build, the barebox build process generates multiple images +(:ref:`multi_image`). All enabled PBLs are each linked with the same +barebox proper binary and then the resulting images are processed to be +in the format expected by the loader. + +The loader is often a BootROM, but maybe another first stage bootloader +or a hardware debugger. diff --git a/Documentation/devel/porting.rst b/Documentation/devel/porting.rst index 9dab2a301f2a..88847f42a8f7 100644 --- a/Documentation/devel/porting.rst +++ b/Documentation/devel/porting.rst @@ -15,83 +15,14 @@ about porting barebox to new hardware. Introduction ************ -Your usual barebox binary consists of two parts. A prebootloader doing -the bare minimum initialization and then the proper barebox binary. +Before starting your barebox port, you'll want to familiarize yourself with +key concepts of the :ref:`barebox architecture <architecture>` namely the +prebootloader, barebox proper and the multi-image support. -barebox proper -============== - -This is the main part of barebox and, like a multi-platform Linux kernel, -is platform-agnostic: The program starts, registers its drivers and tries -to match the drivers with the devices it discovers at runtime. -It initializes file systems and common management facilities and finally -starts an init process. barebox knows no privilege separation and the -init process is built into barebox. -The default init is the :ref:`Hush`, but can be overridden if required. - -For such a platform-agnostic program to work, it must receive external -input about what kind of devices are available: For example, is there a -timer? At what address and how often does it tick? For most barebox -architectures this hardware description is provided in the form -of a flattened device tree (FDT). As part of barebox' initialization -procedure, it unflattens (parses) the device tree and starts probing -(matching) the devices described within with the drivers that are being -registered. - -The device tree can also describe the RAM available in the system. As -walking the device tree itself consumes RAM, barebox proper needs to -be passed information about an initial memory region for use as stack -and for dynamic allocations. When barebox has probed the memory banks, -the whole memory will become available. - -As result of this design, the same barebox proper binary can be reused for -many different boards. Unlike Linux, which can expect a bootloader to pass -it the device tree, barebox *is* the bootloader. For this reason, barebox -proper is prefixed with what is called a prebootloader (PBL). The PBL -handles the low-level details that need to happen before invoking barebox -proper. - -Prebootloader (PBL) -=================== - -The :ref:`prebootloader <pbl>` is a small chunk of code whose objective is -to prepare the environment for barebox proper to execute. This means: - - - Setting up a stack - - Determining a memory region for initial allocations - - Provide the device tree - - Jump to barebox proper - -The prebootloader often runs from a constrained medium like a small -(tens of KiB) on-chip SRAM or sometimes even directly from flash. - -If the size constraints allow, the PBL will contain the barebox proper -binary in compressed form. After ensuring any external DRAM can be -addressed, it will unpack barebox proper there and call it with the -necessary arguments: an initial memory region and the FDT. - -If this is not feasible, the PBL will contain drivers to chain load -barebox proper from the storage medium. As this is usually the same -storage medium the PBL itself was loaded from, shortcuts can often -be taken: e.g. a SD-Card could already be in the correct mode, so the -PBL driver can just read the blocks without having to reinitialize -the SD-card. - -barebox images -============== - -In a typical build, the barebox build process generates multiple images -(:ref:`multi_image`). All enabled PBLs are each linked with the same -barebox proper binary and then the resulting images are processed to be -in the format expected by the loader. - -The loader is often a BootROM, but maybe another first stage bootloader -or a hardware debugger. - -Let us now put these new concepts into practice. We will start by adding -a new board for a platform, for which similar boards already exist. -Then we'll look at adding a new SoC, then a new SoC family and finally -a new architecture. +Once you've read through, let us now put these new concepts into practice. +We will start by adding a new board for a platform, for which similar boards +already exist. Then we'll look at adding a new SoC, then a new SoC family +and finally a new architecture. ********************** Porting to a new board -- 2.39.5
