mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Ahmad Fatoum <a.fatoum@pengutronix.de>
To: barebox@lists.infradead.org
Subject: [PATCH 8/8] Documentation: devel: porting: bring it up-to-date
Date: Mon, 24 Oct 2022 08:57:16 +0200	[thread overview]
Message-ID: <20221024065716.1215046-9-a.fatoum@pengutronix.de> (raw)
In-Reply-To: <20221024065716.1215046-1-a.fatoum@pengutronix.de>

A number of changes happened since this guide was first drafted:

  - We no longer use inline assembly for the header on ARM64, which
    lacks __attribute__((naked))

  - FDT compression algorithm is no longer limited to LZO

Update the guide to reflect this and while at it, fix some typos.
---
 Documentation/devel/porting.rst | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/Documentation/devel/porting.rst b/Documentation/devel/porting.rst
index dea5ebd1c511..f95e8cbba3e4 100644
--- a/Documentation/devel/porting.rst
+++ b/Documentation/devel/porting.rst
@@ -195,14 +195,15 @@ Looking at other boards you might see some different patterns:
    by using ``ENTRY_FUNCTION_WITHSTACK``, which will take care to initialize the
    stack beforehand. If either a barebox assembly entry point,
    ``ENTRY_FUNCTION_WITHSTACK`` or earlier firmware has set up the stack, there is
-   no reason to use ``__naked``, just use ``ENTRY_FNCTION_WITHSTACK`` with a zero
+   no reason to use ``__naked``, just use ``ENTRY_FUNCTION_WITHSTACK`` with a zero
    stack top.
 
 ``noinline``
    Compiler code inlining is oblivious to stack manipulation in
    inline assembly. If you want to ensure a new function has its own stack frame
    (e.g. after setting up the stack in a ``__naked`` function), you must jump to
-   a ``__noreturn noinline`` function.
+   a ``__noreturn noinline`` function. This is already handled by
+   ``ENTRY_FUNCTION_WITHSTACK``.
 
 ``arm_setup_stack``
    For 32-bit ARM, ``arm_setup_stack`` initializes the stack
@@ -214,7 +215,7 @@ Looking at other boards you might see some different patterns:
 ``__dtb_z_my_board_start[];``
    Because the PBL normally doesn't parse anything out
    of the device tree blob, boards can benefit from keeping the device tree blob
-   compressed and only unpack it in barebox proper. Such LZO-compressed device trees
+   compressed and only unpack it in barebox proper. Such compressed device trees
    are prefixed with ``__dtb_z_``. It's usually a good idea to use this.
 
 ``imx6q_barebox_entry(...);``
@@ -232,7 +233,7 @@ Looking at other boards you might see some different patterns:
 
 ``*_start_image(...)/*_load_image(...)/*_xload_*(...)``
    If the SRAM couldn't fit both PBL and the compressed barebox proper, PBL
-   will need to chainload full barebox binary from disk.
+   will need to chainload full barebox binary from the boot medium.
 
 Repeating previous advice: The specifics about how different SoCs handle
 things can vary widely. You're best served by mimicking a similar recently
@@ -404,9 +405,18 @@ New header format
 =================
 
 Your loader may require a specific header or format. If the header is meant
-to be executable, it should preferably be added as inline assembly to
-the start of the PBL entry points. See ``__barebox_arm_head`` and
-``__barebox_riscv_header``. Otherwise, add a new tool to ``scripts/``
+to be executable, it should be written in assembly.
+If the C compiler for that platform supports ``__attribute__((naked))``, it
+can be written in inline assembly inside such a naked function. See for
+example ``__barebox_arm_head`` for ARM32 or ``__barebox_riscv_header`` for RISC-V.
+
+For platforms, without naked function support, inline assembly may not be used
+and the entry point should be written in a dedicated assembly file.
+This is the case with ARM64, see for example ``__barebox_arm64_head`` and the
+``ENTRY_PROC`` macro.
+
+Another way, which is often used for non-executable headers with extra
+meta-information like a checksum, is adding a new tool to ``scripts/``
 and have it run as part the image build process. ``images/`` contains
 various examples.
 
@@ -434,7 +444,7 @@ well as its prerequisites like clocks, resets or pin multiplexers.
 
 Examples for this are the i.MX xload functions. Some BootROMs boot from
 a FAT file system. There is vfat support in the PBL. Refer to the sama5d2
-baord support for an example.
+board support for an example.
 
 Core drivers
 ============
-- 
2.30.2




      parent reply	other threads:[~2022-10-24  6:59 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-10-24  6:57 [PATCH 0/8] ARM64: rewrite ENTRY_FUNCTION_WITHSTACK in assembly Ahmad Fatoum
2022-10-24  6:57 ` [PATCH 1/8] ARM64: cpu: select HAVE_PBL_MULTI_IMAGES globally Ahmad Fatoum
2022-10-24  6:57 ` [PATCH 2/8] ARM64: asm: define ENTRY_FUNCTION in terms of ENTRY_FUNCTION_WITHSTACK Ahmad Fatoum
2022-10-24  6:57 ` [PATCH 3/8] pbl: have linker define __pbl_board_entry alias Ahmad Fatoum
2022-10-24  6:57 ` [PATCH 4/8] asm-generic: memory_layout: define __keep_symbolref() Ahmad Fatoum
2022-10-24  6:57 ` [PATCH 5/8] ARM64: asm: rewrite ENTRY_FUNCTION(_WITHSTACK) fully in assembly Ahmad Fatoum
2022-10-24  8:55   ` Sascha Hauer
2022-10-24 10:02     ` Ahmad Fatoum
2022-10-24 12:11   ` [PATCH] fixup! " Ahmad Fatoum
2022-10-24  6:57 ` [PATCH 6/8] ARM64: asm: drop __barebox_arm_head Ahmad Fatoum
2022-10-24  6:57 ` [PATCH 7/8] ARM: asm: cleanup 32-bit entry points Ahmad Fatoum
2022-10-24  6:57 ` Ahmad Fatoum [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20221024065716.1215046-9-a.fatoum@pengutronix.de \
    --to=a.fatoum@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    --subject='Re: [PATCH 8/8] Documentation: devel: porting: bring it up-to-date' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox