aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile1
-rw-r--r--doc/board/index.rst1
-rw-r--r--doc/board/purism/index.rst9
-rw-r--r--doc/board/purism/librem5.rst60
-rw-r--r--doc/develop/bootstd.rst2
-rw-r--r--doc/develop/index.rst1
-rw-r--r--doc/develop/process.rst87
-rw-r--r--doc/develop/release_cycle.rst4
-rw-r--r--doc/develop/sending_patches.rst444
-rw-r--r--doc/device-tree-bindings/firmware/fwu-mdata-mtd.yaml38
-rw-r--r--doc/imx/habv4/csf_examples/mx8m/csf.sh77
-rw-r--r--doc/imx/habv4/csf_examples/mx8m/csf_fit.txt36
-rw-r--r--doc/imx/habv4/csf_examples/mx8m/csf_spl.txt33
-rw-r--r--doc/imx/habv4/guides/mx8m_spl_secure_boot.txt265
-rw-r--r--doc/usage/cmd/gpio.rst42
-rw-r--r--doc/usage/cmd/tftpput.rst87
-rw-r--r--doc/usage/index.rst1
17 files changed, 1168 insertions, 20 deletions
diff --git a/doc/Makefile b/doc/Makefile
index 6081858..f5de65e 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -58,6 +58,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
$(SPHINXBUILD) \
-j$(shell nproc) \
-b $2 \
+ -j auto \
-c $(abspath $(srctree)/$(src)) \
-d $(abspath $(BUILDDIR)/.doctrees/$3) \
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
diff --git a/doc/board/index.rst b/doc/board/index.rst
index 01b99f9..53edd53 100644
--- a/doc/board/index.rst
+++ b/doc/board/index.rst
@@ -28,6 +28,7 @@ Board-specific doc
nokia/index
nxp/index
openpiton/index
+ purism/index
qualcomm/index
rockchip/index
samsung/index
diff --git a/doc/board/purism/index.rst b/doc/board/purism/index.rst
new file mode 100644
index 0000000..a9cdc31
--- /dev/null
+++ b/doc/board/purism/index.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Purism SPC
+==========
+
+.. toctree::
+ :maxdepth: 2
+
+ librem5
diff --git a/doc/board/purism/librem5.rst b/doc/board/purism/librem5.rst
new file mode 100644
index 0000000..fb050c6
--- /dev/null
+++ b/doc/board/purism/librem5.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Librem5
+==========
+
+U-Boot for the Purism Librem5 phone
+
+Quick Start
+-----------
+
+- Build the ARM Trusted firmware binary
+- Get ddr and hdmi firmware
+- Build U-Boot
+
+Get and Build the ARM Trusted firmware
+--------------------------------------
+
+Note: srctree is U-Boot source directory
+Get ATF from: https://source.puri.sm/Librem5/arm-trusted-firmware
+branch: librem5
+
+.. code-block:: bash
+
+ $ make PLAT=imx8mq CROSS_COMPILE=aarch64-linux-gnu- bl31
+ $ cp build/imx8mq/release/bl31.bin $(builddir)
+
+Get the ddr and display port firmware
+-------------------------------------
+
+.. code-block:: bash
+
+ $ wget https://www.nxp.com/lgfiles/NMG/MAD/YOCTO/firmware-imx-8.15.bin
+ $ chmod +x firmware-imx-8.15.bin
+ $ ./firmware-imx-8.15.bin
+ $ cp firmware-imx-8.15/firmware/hdmi/cadence/signed_dp_imx8m.bin $(builddir)
+ $ cp firmware-imx-8.15/firmware/ddr/synopsys/lpddr4*.bin $(builddir)
+
+Build U-Boot
+------------
+
+.. code-block:: bash
+
+ $ export CROSS_COMPILE=aarch64-linux-gnu-
+ $ make librem5_defconfig
+ $ make ARCH=arm
+
+Burn the flash.bin
+------------------
+
+Use uuu to burn flash.bin. Power on the phone while holding vol+ to get it
+into uuu mode.
+
+.. code-block:: bash
+
+ $ git clone https://source.puri.sm/Librem5/librem5-devkit-tools.git
+ $ cd librem5-devkit-tools
+ $ cp $(builddir)/flash.bin files/u-boot-librem5.imx
+ $ uuu uuu_scripts/u-boot_flash_librem5.lst
+
+Reboot the phone.
diff --git a/doc/develop/bootstd.rst b/doc/develop/bootstd.rst
index f7fc725..1ccc494 100644
--- a/doc/develop/bootstd.rst
+++ b/doc/develop/bootstd.rst
@@ -322,7 +322,7 @@ look like this::
The `sf-bootdev` driver can implement a way to read from the SPI flash, using
the offset and size provided, and return that bootflow file back to the caller.
-When distro boot wants to read the kernel it calls disto_getfile() which must
+When distro boot wants to read the kernel it calls distro_getfile() which must
provide a way to read from the SPI flash. See `distro_boot()` at distro_boot_
for more details.
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index ce6b38e..5934d9f 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -11,6 +11,7 @@ General
codingstyle
designprinciples
+ patman
process
release_cycle
system_configuration
diff --git a/doc/develop/process.rst b/doc/develop/process.rst
index 388945c..0fa0143 100644
--- a/doc/develop/process.rst
+++ b/doc/develop/process.rst
@@ -108,6 +108,8 @@ Differences to the Linux Development Process
In U-Boot, ``"-rc1"`` will only be released after all (or at least most of
the) patches that were submitted during the merge window have been applied.
+.. _custodians:
+
Custodians
----------
@@ -127,31 +129,88 @@ patch, these should leave no doubt if they were just comments and the
patch will be accepted anyway, or if the patch should be
reworked/resubmitted, or if it was rejected.
-Work flow of a Custodian
+Review Process, Git Tags
------------------------
-The normal flow of work in the U-Boot development process will look
-like this:
+There are a number of *git tags* that are used to document the origin and the
+processing of patches on their way into the mainline U-Boot code. The following
+is an attempt to document how these are usually handled in the U-Boot project.
+
+In general, we try to follow the established procedures from other projects,
+especially the Linux kernel, but there may be smaller differences. For
+reference, see the Linux kernel's `Submitting patches
+<https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_
+document.
+
+.. _dco:
+
+* Signed-off-by: the *Signed-off-by:* is a line at the end of the commit
+ message by which the signer certifies that they were involved in the development
+ of the patch and that they accept the `Developer Certificate of Origin
+ <https://developercertificate.org/>`_. Following this and adding a
+ ``Signed-off-by:`` line that contains the developer's name and email address
+ is required.
-#. A developer submits a patch via e-mail to the u-boot mailing list. In
- U-Boot, we make use of the `Developer Certificate of Origin
- <https://developercertificate.org/>`_ that is common in other projects such
- as the Linux kernel. Following this and adding a ``Signed-off-by:`` line
- that contains the developer's name and email address is required.
+ * Please note that in U-Boot, we do not add a ``Signed-off-by`` tag if we
+ just pass on a patch without any changes.
* Please note that when importing code from other projects you must say
where it comes from, and what revision you are importing. You must not
however copy ``Signed-off-by`` or other tags.
-#. Everybody who can is invited to review and test the changes. Typically, we
- follow the same guidelines as the Linux kernel for `Acked-by
- <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by>`_
- as well as `Reviewed-by
- <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_
- and similar additional tags.
+* Everybody who can is invited to review and test the changes. Typically, we
+ follow the same guidelines as the Linux kernel for `Acked-by
+ <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by>`_
+ as well as `Reviewed-by
+ <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_
+ and similar additional tags.
+
+* Reviewed-by: The patch has been reviewed and found acceptible according to
+ the `Reveiwer's statement of oversight
+ <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight>`_.
+ A *Reviewed-by:* tag is a statement of opinion that the patch is an
+ appropriate modification of the code without any remaining serious technical
+ issues. Any interested reviewer (who has done the work) can offer a
+ *Reviewed-by:* tag for a patch.
+
+* Acked-by: If a person was not directly involved in the preparation or
+ handling of a patch but wishes to signify and record their approval of it
+ then they can arrange to have an *Acked-by:* line added to the patch's
+ changelog.
+
+* Tested-by: A *Tested-by:* tag indicates that the patch has been successfully
+ tested (in some environment) by the person named. Andrew Morton: "I think
+ it's very useful information to have. For a start, it tells you who has the
+ hardware and knows how to build a kernel. So if you're making a change to a
+ driver and want it tested, you can troll the file's changelog looking for
+ people who might be able to help."
+
+* Reported-by: If this patch fixes a problem reported by somebody else,
+ consider adding a *Reported-by:* tag to credit the reporter for their
+ contribution. Please note that this tag should not be added without the
+ reporter's permission, especially if the problem was not reported in a public
+ forum.
+
+* Cc: If a person should have the opportunity to comment on a patch, you may
+ optionally add a *Cc:* tag to the patch. Git tools (git send-email) will then
+ automatically arrange that they receives a copy of the patch when you submit it
+ to the mainling list. This is the only tag which might be added without an
+ explicit action by the person it names. This tag documents that potentially
+ interested parties have been included in the discussion.
+ For example, when your change affects a specific board or driver, then makes
+ a lot of sense to put the respective maintainer of this code on Cc:
+
+Work flow of a Custodian
+------------------------
+
+The normal flow of work in the U-Boot development process will look
+like this:
#. The responsible custodian inspects this patch, especially for:
+ #. The commit message is useful, descriptive and makes correct and
+ appropraite usage of required *git tags*.
+
#. :doc:`codingstyle`
#. Basic logic:
diff --git a/doc/develop/release_cycle.rst b/doc/develop/release_cycle.rst
index b75576c..7d8a610 100644
--- a/doc/develop/release_cycle.rst
+++ b/doc/develop/release_cycle.rst
@@ -68,9 +68,9 @@ For the next scheduled release, release candidates were made on::
* U-Boot v2022.10-rc3 was released on Mon 22 August 2022.
-.. * U-Boot v2022.10-rc4 was released on Mon 05 September 2022.
+* U-Boot v2022.10-rc4 was released on Mon 05 September 2022.
-.. * U-Boot v2022.10-rc5 was released on Mon 19 September 2022.
+* U-Boot v2022.10-rc5 was released on Mon 19 September 2022.
Please note that the following dates are planned only and may be deviated from
as needed.
diff --git a/doc/develop/sending_patches.rst b/doc/develop/sending_patches.rst
index 0542ade..1730756 100644
--- a/doc/develop/sending_patches.rst
+++ b/doc/develop/sending_patches.rst
@@ -3,14 +3,452 @@
Sending patches
===============
-.. toctree::
- :maxdepth: 2
+*Before you begin* to implement any new ideas or concepts it is always a good
+idea to present your plans on the `U-Boot mailing list
+<https://lists.denx.de/listinfo/u-boot>`_. U-Boot supports a huge amount of
+very different systems, and it is often impossible for the individual developer
+to oversee the consequences of a specific change to all architectures.
+Discussing concepts early can help you to avoid spending effort on code which,
+when submitted as a patch, might be rejected and/or will need lots of rework
+because it does not fit for some reason. Early peer review is an important
+resource - use it. Being familiar with the :doc:`process` is also important.
- patman
+A good introduction how to prepare for submitting patches can be found in the
+LWN article `How to Get Your Change Into the Linux Kernel
+<http://lwn.net/Articles/139918/>`_ as the same rules apply to U-Boot, too.
+Using patman
+------------
You can use a tool called patman to prepare, check and sent patches. It creates
change logs, cover letters and patch notes. It also simplified the process of
sending multiple versions of a series.
See more details at :doc:`patman`.
+
+General Patch Submission Rules
+------------------------------
+
+* All patches must be sent to the `u-boot@lists.denx.de
+ <https://lists.denx.de/listinfo/u-boot>`_ mailing list.
+
+* If your patch affects the code maintained by one of the :ref:`custodians`, CC
+ them when emailing your patch. The easiest way to make sure you don't forget
+ this even when you resubmit the patch later is to add a ``Cc: name
+ <address>`` line after your ``Signed-off-by:`` line (see the example below).
+
+* Take a look at the commit logs of the files you are modifying. Authors of
+ past commits might have input to your change, so also CC them if you think
+ they may have feedback.
+
+* Patches should always contain exactly one complete logical change, i. e.
+
+ * Changes that contain different, unrelated modifications shall be submitted
+ as *separate* patches, one patch per changeset.
+
+ * If one logical set of modifications affects or creates several files, all
+ these changes shall be submitted in a *single* patch.
+
+* Non-functional changes, i.e. whitespace and reformatting changes, should be
+ done in separate patches marked as ``cosmetic``. This separation of functional
+ and cosmetic changes greatly facilitates the review process.
+
+* Some comments on running :doc:`checkpatch.pl <checkpatch>`:
+
+ * Checkpatch is a tool that can help you find some style problems, but is
+ imperfect, and the things it complains about are of varying importance.
+ So use common sense in interpreting the results.
+
+ * Warnings that clearly only make sense in the Linux kernel can be ignored.
+ This includes ``Use #include <linux/$file> instead of <asm/$file>`` for
+ example.
+
+ * If you encounter warnings for existing code, not modified by your patch,
+ consider submitting a separate, cosmetic-only patch -- clearly described
+ as such -- that *precedes* your substantive patch.
+
+ * For minor modifications (e.g. changed arguments of a function call),
+ adhere to the present codingstyle of the module. Relating checkpatch
+ warnings can be ignored in this case. A respective note in the commit or
+ cover letter why they are ignored is desired.
+
+* Send your patches as plain text messages: no HTML, no MIME, no links, no
+ compression, no attachments. Just plain text. The best way the generate
+ patches is by using the ``git format-patch`` command. Please use the
+ ``master`` branch of the mainline U-Boot git repository
+ (``https://source.denx.de/u-boot/u-boot.git``) as reference, unless (usually
+ late in a release cycle) there has been an announcement to use the ``next``
+ branch of this repository instead.
+
+* Make sure that your mailer does not mangle the patch by automatic changes
+ like wrapping of longer lines etc.
+ The best way to send patches is by not using your regular mail tool, but by
+ using either ``git send-email`` or the ``git imap-send`` command instead.
+ If you believe you need to use a mailing list for testing (instead of any
+ regular mail address you own), we have a special test list for such purposes.
+ It would be best to subscribe to the list for the duration of your tests to
+ avoid repeated moderation - see https://lists.denx.de/listinfo/test
+
+* Choose a meaningful Subject: - keep in mind that the Subject will also be
+ visible as headline of your commit message. Make sure the subject does not
+ exceed 60 characters or so.
+
+* The start of the subject should be a meaningfull tag (arm:, ppc:, tegra:,
+ net:, ext2:, etc)
+
+* Include the string "PATCH" in the Subject: line of your message, e. g.
+ "[PATCH] Add support for feature X". ``git format-patch`` should automatically
+ do this.
+
+* If you are sending a patch series composed of multiple patches, make sure
+ their titles clearly state the patch order and total number of patches (``git
+ format-patch -n``). Also, often times an introductory email describing what
+ the patchset does is useful (``git format-patch -n --cover-letter``). As an
+ example::
+
+ [PATCH 0/3] Add support for new SuperCPU2000
+ (This email does not contain a patch, just a description)
+ [PATCH 1/3] Add core support for SuperCPU2000
+ [PATCH 2/3] Add support for SuperCPU2000's on-chip I2C controller
+ [PATCH 3/3] Add support for SuperCPU2000's on-chip UART
+
+* In the message body, include a description of your changes.
+
+ * For bug fixes: a description of the bug and how your patch fixes this bug.
+ Please try to include a way of demonstrating that the patch actually fixes
+ something.
+
+ * For new features: a description of the feature and your implementation.
+
+* Additional comments which you don't want included in U-Boot's history can be
+ included below the first "---" in the message body.
+
+* If your description gets too long, that's a strong indication that you should
+ split up your patch.
+
+* Remember that there is a size limit of 100 kB on the mailing list. In most
+ cases, you did something wrong if your patch exceeds this limit. Think again
+ if you should not split it into separate logical parts.
+
+Attributing Code, Copyrights, Signing
+-------------------------------------
+
+* Sign your changes, i. e. add a *Signed-off-by:* line to the message body.
+ This can be automated by using ``git commit -s``. Please see the
+ :ref:`Developer Certificate of Origin <dco>` section for more details here.
+
+* If you change or add *significant* parts to a file, then please make sure to
+ add your copyright to that file, for example like this::
+
+ (C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com>
+
+ Please do *not* include a detailed description of your
+ changes. We use the *git* commit messages for this purpose.
+
+* If you add new files, please always make sure that these contain your
+ copyright note and a GPLv2+ SPDX-License-Identifier, for example like this::
+
+ (C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com>
+
+ SPDX-License-Identifier:<TAB>GPL-2.0+
+
+* If you are copying or adapting code from other projects, like the Linux
+ kernel, or BusyBox, or similar, please make sure to state clearly where you
+ copied the code from, and provide terse but precise information which exact
+ version or even commit ID was used. Follow the ideas of this note from the
+ Linux "SubmittingPatches" document::
+
+ Special note to back-porters: It seems to be a common and useful practice
+ to insert an indication of the origin of a patch at the top of the commit
+ message (just after the subject line) to facilitate tracking. For instance,
+ here's what we see in 2.6-stable :
+
+ Date: Tue May 13 19:10:30 2008 +0000
+
+ SCSI: libiscsi regression in 2.6.25: fix nop timer handling
+
+ commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
+
+ And here's what appears in 2.4 :
+
+ Date: Tue May 13 22:12:27 2008 +0200
+
+ wireless, airo: waitbusy() won't delay
+
+ [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
+
+Whatever the format, this information provides a valuable help to people
+tracking your trees, and to people trying to trouble-shoot bugs in your
+tree.
+
+Commit message conventions
+--------------------------
+
+Please adhere to the following conventions when writing your commit
+log messages.
+
+* The first line of the log message is the summary line. Keep this less than 70
+ characters long.
+
+* Don't use periods to end the summary line (e.g., don't do "Add support for
+ X.")
+
+* Use the present tense in your summary line (e.g., "Add support for X" rather
+ than "Added support for X"). Furthermore, use the present tense in your log
+ message to describe what the patch is doing. This isn't a strict rule -- it's
+ OK to use the past tense for describing things that were happening in the old
+ code for example.
+
+* Use the imperative tense in your summary line (e.g., "Add support for X"
+ rather than "Adds support for X"). In general, you can think of the summary
+ line as "this commit is meant to 'Add support for X'"
+
+* If applicable, prefix the summary line with a word describing what area of
+ code is being affected followed by a colon. This is a standard adopted by
+ both U-Boot and Linux. For example, if your change affects all mpc85xx
+ boards, prefix your summary line with "mpc85xx:". If your change affects the
+ PCI common code, prefix your summary line with "pci:". The best thing to do
+ is look at the "git log <file>" output to see what others have done so you
+ don't break conventions.
+
+* Insert a blank line after the summary line
+
+* For bug fixes, it's good practice to briefly describe how things behaved
+ before this commit
+
+* Put a detailed description after the summary and blank line. If the summary
+ line is sufficient to describe the change (e.g. it is a trivial spelling
+ correction or whitespace update), you can omit the blank line and detailed
+ description.
+
+* End your log message with S.O.B. (Signed-off-by) line. This is done
+ automatically when you use ``git commit -s``. Please see the
+ :ref:`Developer Certificate of Origin <dco>` section for more details here.
+
+* Keep EVERY line under 72 characters. That is, your message should be
+ line-wrapped with line-feeds. However, don't get carried away and wrap it too
+ short either since this also looks funny.
+
+* Detail level: The audience of the commit log message that you should cater to
+ is those familiar with the underlying source code you are modifying, but who
+ are _not_ familiar with the patch you are submitting. They should be able to
+ determine what is being changed and why. Avoid excessive low-level detail.
+ Before submitting, re-read your commit log message with this audience in mind
+ and adjust as needed.
+
+Sending updated patch versions
+------------------------------
+
+It is pretty normal that the first version of a patch you are submitting does
+not get accepted as is, and that you are asked to submit another, improved
+version.
+
+When re-posting such a new version of your patch(es), please always make sure
+to observe the following rules.
+
+* Make an appropriate note that this is a re-submission in the subject line,
+ eg. "[PATCH v2] Add support for feature X". ``git format-patch
+ --subject-prefix="PATCH v2"`` can be used in this case (see the example
+ below).
+
+* Please make sure to keep a "change log", i. e. a description of what you have
+ changed compared to previous versions of this patch. This change log should
+ be added below the "---" line in the patch, which starts the "comment
+ section", i. e. which contains text that does not get included into the
+ actual commit message.
+ Note: it is *not* sufficient to provide a change log in some cover letter
+ that gets sent as a separate message with the patch series. The reason is
+ that such cover letters are not as easily reviewed in our `patchwork queue
+ <http://patchwork.ozlabs.org/project/uboot/list/>`_ so they are not helpful
+ to any reviewers using this tool. Example::
+
+ From: Joe Hacker <jh@hackers.paradise.com>
+ Date: Thu, 1 Jan 2222 12:21:22 +0200
+ Subject: [PATCH 1/2 v3] FOO: add timewarp-support
+
+ This patch adds timewarp-support for the FOO family of processors.
+
+ adapted for the current kernel structures.
+
+ Signed-off-by: Joe Hacker <jh@hackers.paradise.com>
+ Cc: Tom Maintainer <tm@u-boot.custodians.org>
+ ---
+ Changes for v2:
+ - Coding Style cleanup
+ - fixed miscalculation of time-space discontinuities
+ Changes for v3:
+ - fixed compiler warnings observed with GCC-17.3.5
+ - worked around integer overflow in warp driver
+
+ arch/foo/cpu/spacetime.c | 8 +
+ drivers/warp/Kconfig | 7 +
+ drivers/warp/Makefile | 42 +++
+ drivers/warp/warp-core.c | 255 +++++++++++++++++++++++++
+
+* Make sure that your mailer adds or keeps correct ``In-reply-to:`` and
+ ``References:`` headers, so threading of messages is working and everybody
+ can see that the new message refers to some older posting of the same topic.
+
+Uncommented and un-threaded repostings are extremely annoying and
+time-consuming, as we have to try to remember if anything similar has been
+posted before, look up the old threads, and then manually compare if anything
+has been changed, or what.
+
+If you have problems with your e-mail client, for example because it mangles
+white space or wraps long lines, then please read this article about `Email
+Clients and Patches <http://kerneltrap.org/Linux/Email_Clients_and_Patches>`_.
+
+Notes
+-----
+
+1. U-Boot is Free Software that can redistributed and/or modified under the
+ terms of the `GNU General Public License
+ <http://www.fsf.org/licensing/licenses/gpl.html>`_ (GPL). Currently (August
+ 2022) version 2 of the GPL applies. Please see :download:`Licensing
+ <../../Licenses/README>` for details. To allow that later versions of U-Boot
+ may be released under a later version of the GPL, all new code that gets
+ added to U-Boot shall use a "GPL-2.0+" SPDX-License-Identifier.
+
+2. All code must follow the :doc:`codingstyle` requirements.
+
+3. Before sending the patch, you *must* run some form of local testing.
+ Submitting a patch that does not build or function correct is a mistake. For
+ non-trivial patches, either building a number of platforms locally or making
+ use of :doc:`ci_testing` is strongly encouraged in order to avoid problems
+ that can be found when attempting to merge the patch.
+
+4. If you modify existing code, make sure that your new code does not add to
+ the memory footprint of the code. Remember: Small is beautiful! When adding
+ new features follow the guidelines laid out in :doc:`system_configuration`.
+
+Patch Tracking
+--------------
+
+Like some other projects, U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`_
+to track the state of patches. This is one of the reasons why it is mandatory
+to submit all patches to the U-Boot mailing list - only then they will be
+picked up by patchwork.
+
+At http://patchwork.ozlabs.org/project/uboot/list/ you can find the list of
+open U-Boot patches. By using the "Filters" link (Note: requires JavaScript)
+you can also select other views, for example, to include old patches that have,
+for example, already been applied or rejected.
+
+Note that Patchwork automatically tracks and collects a number of git tags from
+follow-up mails, so it is usually better to apply a patch through the Patchwork
+commandline interface than just manually applying it from a posting on the
+mailing list (in which case you have to do all the tracking and adding of git
+tags yourself). This also obviates the need of a developer to resubmit a patch
+only in order to collect these tags.
+
+A Custodian has additional privileges and can:
+
+* **Delegate** a patch
+
+* **Change the state** of a patch. The following states exist:
+
+ * New
+
+ * Under Review
+
+ * Accepted
+
+ * Rejected
+
+ * RFC
+
+ * Not Applicable
+
+ * Changes Requested
+
+ * Awaiting Upstream
+
+ * Superseeded
+
+ * Deferred
+
+ * Archived
+
+Patchwork work-flow
+^^^^^^^^^^^^^^^^^^^
+
+The following are a "rule of thumb" as to how the states are used in patchwork
+today. Not all states are used by all custodians.
+
+* New: Patch has been submitted to the list, and none of the maintainers has
+ changed it's state since.
+
+* Under Review: A custodian is reviewing the patch currently.
+
+* Accepted: When a patch has been applied to a custodian repository that gets
+ used for pulling from into upstream, they are put into "accepted" state.
+
+* Rejected: Rejected means we just don't want to do what the patch does.
+
+* RFC: The patch is not intended to be applied to any of the mainline
+ repositories, but merely for discussing or testing some idea or new feature.
+
+* Not Applicable: The patch either was not intended to be applied, as it was
+ a debugging or discussion aide that patchwork picked up, or was cross-posted
+ to our list but intended for another project entirely.
+
+* Changes Requested: The patch looks mostly OK, but requires some rework before
+ it will be accepted for mainline.
+
+* Awaiting Upstream: A custodian may have applied this to the ``next`` branch
+ and has not merged yet to master, or has queued the patch up to be submitted
+ to be merged, but has not yet.
+
+* Superseeded: Patches are marked as 'superseeded' when the poster submits a
+ new version of these patches.
+
+* Deferred: Deferred usually means the patch depends on something else that
+ isn't upstream, such as patches that only apply against some specific other
+ repository. This is also used when a patch has been in patchwork for over a
+ year and it is unlikely to be applied as-is.
+
+* Archived: Archiving puts the patch away somewhere where it doesn't appear in
+ the normal pages and needs extra effort to get to.
+
+Apply patches
+^^^^^^^^^^^^^
+
+To apply a patch from the `patchwork queue
+<http://patchwork.ozlabs.org/project/uboot/list/>`_ using ``git``, download the
+mbox file and apply it using::
+
+ git am file
+
+The `openembedded wiki <http://wiki.openembedded.net/>`_ also provides a script
+named `pw-am.sh
+<http://cgit.openembedded.org/cgit.cgi/openembedded/tree/contrib/patchwork/pw-am.sh>`_
+which can be used to fetch an 'mbox' patch from patchwork and git am it::
+
+ usage: pw-am.sh <number>
+ example: 'pw-am.sh 71002' will get and apply the patch from http://patchwork.ozlabs.org/patch/71002/
+
+Update the state of patches
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You have to register to be able to update the state of patches. You can use the
+Web interface, `pwclient`, or `pwparser`.
+
+pwclient
+^^^^^^^^
+
+The `pwclient` command line tool can be used for example to retrieve patches,
+search the queue or update the state.
+
+All necessary information for `pwclient` is linked from the bottom of
+http://patchwork.ozlabs.org/project/uboot/
+
+Use::
+
+ pwclient help
+
+for an overview on how to use it.
+
+pwparser
+^^^^^^^^
+
+See http://www.mail-archive.com/patchwork@lists.ozlabs.org/msg00057.html
diff --git a/doc/device-tree-bindings/firmware/fwu-mdata-mtd.yaml b/doc/device-tree-bindings/firmware/fwu-mdata-mtd.yaml
new file mode 100644
index 0000000..4f5404f
--- /dev/null
+++ b/doc/device-tree-bindings/firmware/fwu-mdata-mtd.yaml
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/firmware/u-boot,fwu-mdata-sf.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: FWU metadata on MTD device without GPT
+
+maintainers:
+ - Masami Hiramatsu <masami.hiramatsu@linaro.org>
+
+properties:
+ compatible:
+ items:
+ - const: u-boot,fwu-mdata-mtd
+
+ fwu-mdata-store:
+ maxItems: 1
+ description: Phandle of the MTD device which contains the FWU medatata.
+
+ mdata-offsets:
+ minItems: 2
+ description: Offsets of the primary and secondary FWU metadata in the NOR flash.
+
+required:
+ - compatible
+ - fwu-mdata-store
+ - mdata-offsets
+
+additionalProperties: false
+
+examples:
+ - |
+ fwu-mdata {
+ compatible = "u-boot,fwu-mdata-mtd";
+ fwu-mdata-store = <&spi-flash>;
+ mdata-offsets = <0x500000 0x530000>;
+ };
diff --git a/doc/imx/habv4/csf_examples/mx8m/csf.sh b/doc/imx/habv4/csf_examples/mx8m/csf.sh
new file mode 100644
index 0000000..6898513
--- /dev/null
+++ b/doc/imx/habv4/csf_examples/mx8m/csf.sh
@@ -0,0 +1,77 @@
+#!/bin/sh
+
+# 0) Generate keys
+#
+# WARNING: ECDSA keys are only supported by HAB 4.5 and newer (i.e. i.MX8M Plus)
+#
+# cd /path/to/cst-3.3.1/keys/
+# ./hab4_pki_tree.sh -existing-ca n -use-ecc n -kl 4096 -duration 10 -num-srk 4 -srk-ca y
+# cd /path/to/cst-3.3.1/crts/
+# ../linux64/bin/srktool -h 4 -t SRK_1_2_3_4_table.bin -e SRK_1_2_3_4_fuse.bin -d sha256 -c ./SRK1_sha256_4096_65537_v3_ca_crt.pem,./SRK2_sha256_4096_65537_v3_ca_crt.pem,./SRK3_sha256_4096_65537_v3_ca_crt.pem,./SRK4_sha256_4096_65537_v3_ca_crt.pem -f 1
+
+# 1) Build U-Boot (e.g. for i.MX8MM)
+#
+# export ATF_LOAD_ADDR=0x920000
+# cp -Lv /path/to/arm-trusted-firmware/build/imx8mm/release/bl31.bin .
+# cp -Lv /path/to/firmware-imx-8.14/firmware/ddr/synopsys/ddr3* .
+# make -j imx8mm_board_defconfig
+# make -j`nproc` flash.bin
+
+# 2) Sign SPL and DRAM blobs
+
+cp doc/imx/habv4/csf_examples/mx8m/csf_spl.txt csf_spl.tmp
+cp doc/imx/habv4/csf_examples/mx8m/csf_fit.txt csf_fit.tmp
+
+spl_block_base=$(printf "0x%x" $(( $(sed -n "/CONFIG_SPL_TEXT_BASE=/ s@.*=@@p" .config) - 0x40)) )
+spl_block_size=$(printf "0x%x" $(stat -tc %s u-boot-spl-ddr.bin))
+sed -i "/Blocks = / s@.*@ Blocks = $spl_block_base 0x0 $spl_block_size \"flash.bin\"@" csf_spl.tmp
+
+# Generate CSF blob
+cst -i csf_spl.tmp -o csf_spl.bin
+
+# Patch CSF blob into flash.bin
+spl_csf_offset=$(xxd -s 24 -l 4 -e flash.bin | cut -d " " -f 2 | sed "s@^@0x@")
+spl_bin_offset=$(xxd -s 4 -l 4 -e flash.bin | cut -d " " -f 2 | sed "s@^@0x@")
+spl_dd_offset=$((${spl_csf_offset} - ${spl_bin_offset} + 0x40))
+dd if=csf_spl.bin of=flash.bin bs=1 seek=${spl_dd_offset} conv=notrunc
+
+# 3) Sign u-boot.itb
+
+# fitImage tree
+fit_block_base=$(printf "0x%x" $(( $(sed -n "/CONFIG_SYS_TEXT_BASE=/ s@.*=@@p" .config) - $(sed -n "/CONFIG_FIT_EXTERNAL_OFFSET=/ s@.*=@@p" .config) - 0x200 - 0x40)) )
+fit_block_offset=$(printf "0x%s" $(fdtget -t x u-boot.dtb /binman/imx-boot/uboot offset))
+fit_block_size=$(printf "0x%x" $(( ( $(fdtdump u-boot.itb 2>/dev/null | sed -n "/^...totalsize:/ s@.*\(0x[0-9a-f]\+\).*@\1@p") + 0x1000 - 0x1 ) & ~(0x1000 - 0x1) + 0x20 )) )
+sed -i "/Blocks = / s@.*@ Blocks = $fit_block_base $fit_block_offset $fit_block_size \"flash.bin\", \\\\@" csf_fit.tmp
+
+# U-Boot
+uboot_block_base=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/uboot load))
+uboot_block_offset=$(printf "0x%x" $(( $(printf "0x%s" $(fdtget -t x u-boot.itb /images/uboot data-position)) + ${fit_block_offset} )))
+uboot_block_size=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/uboot data-size))
+sed -i "/0xuuuu/ s@.*@ $uboot_block_base $uboot_block_offset $uboot_block_size \"flash.bin\", \\\\@" csf_fit.tmp
+
+# ATF
+atf_block_base=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/atf load))
+atf_block_offset=$(printf "0x%x" $(( $(printf "0x%s" $(fdtget -t x u-boot.itb /images/atf data-position)) + ${fit_block_offset} )))
+atf_block_size=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/atf data-size))
+sed -i "/0xaaaa/ s@.*@ $atf_block_base $atf_block_offset $atf_block_size \"flash.bin\", \\\\@" csf_fit.tmp
+
+# DTB
+dtb_block_base=$(printf "0x%x" $(( ${uboot_block_base} + ${uboot_block_size} )))
+dtb_block_offset=$(printf "0x%x" $(( $(printf "0x%s" $(fdtget -t x u-boot.itb /images/fdt-1 data-position)) + ${fit_block_offset} )))
+dtb_block_size=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/fdt-1 data-size))
+sed -i "/0xdddd/ s@.*@ $dtb_block_base $dtb_block_offset $dtb_block_size \"flash.bin\"@" csf_fit.tmp
+
+# IVT
+ivt_ptr_base=$(printf "%08x" ${fit_block_base} | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@")
+ivt_block_base=$(printf "%08x" $(( ${fit_block_base} + ${fit_block_size} - 0x20 )) | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@")
+csf_block_base=$(printf "%08x" $(( ${fit_block_base} + ${fit_block_size} )) | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@")
+ivt_block_offset=$((${fit_block_offset} + ${fit_block_size} - 0x20))
+csf_block_offset=$((${ivt_block_offset} + 0x20))
+
+echo "0xd1002041 ${ivt_ptr_base} 0x00000000 0x00000000 0x00000000 ${ivt_block_base} ${csf_block_base} 0x00000000" | xxd -r -p > ivt.bin
+dd if=ivt.bin of=flash.bin bs=1 seek=${ivt_block_offset} conv=notrunc
+
+# Generate CSF blob
+cst -i csf_fit.tmp -o csf_fit.bin
+# Patch CSF blob into flash.bin
+dd if=csf_fit.bin of=flash.bin bs=1 seek=${csf_block_offset} conv=notrunc
diff --git a/doc/imx/habv4/csf_examples/mx8m/csf_fit.txt b/doc/imx/habv4/csf_examples/mx8m/csf_fit.txt
new file mode 100644
index 0000000..cd1d407
--- /dev/null
+++ b/doc/imx/habv4/csf_examples/mx8m/csf_fit.txt
@@ -0,0 +1,36 @@
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ # FIXME: Adjust path here
+ File = "/path/to/cst-3.3.1/crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ # FIXME: Adjust path here
+ File = "/path/to/cst-3.3.1/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Install Key]
+ Verification index = 0
+ Target Index = 2
+ # FIXME: Adjust path here
+ File = "/path/to/cst-3.3.1/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ Verification index = 2
+ # FIXME:
+ # Line 1 -- fitImage tree
+ # Line 2 -- U-Boot u-boot-nodtb.bin blob
+ # Line 3 -- ATF BL31 blob
+ # Line 4 -- DT blob
+ Blocks = 0x401fcdc0 0x57c00 0xffff "flash.bin", \
+ 0x40200000 0x62c00 0xuuuu "flash.bin", \
+ 0x920000 0x00000 0xaaaa "flash.bin", \
+ 0x40200000 0x00000 0xdddd "flash.bin"
diff --git a/doc/imx/habv4/csf_examples/mx8m/csf_spl.txt b/doc/imx/habv4/csf_examples/mx8m/csf_spl.txt
new file mode 100644
index 0000000..00e34f6
--- /dev/null
+++ b/doc/imx/habv4/csf_examples/mx8m/csf_spl.txt
@@ -0,0 +1,33 @@
+[Header]
+ Version = 4.3
+ Hash Algorithm = sha256
+ Engine = CAAM
+ Engine Configuration = 0
+ Certificate Format = X509
+ Signature Format = CMS
+
+[Install SRK]
+ # FIXME: Adjust path here
+ File = "/path/to/cst-3.3.1/crts/SRK_1_2_3_4_table.bin"
+ Source index = 0
+
+[Install CSFK]
+ # FIXME: Adjust path here
+ File = "/path/to/cst-3.3.1/crts/CSF1_1_sha256_4096_65537_v3_usr_crt.pem"
+
+[Authenticate CSF]
+
+[Unlock]
+ Engine = CAAM
+ Features = MID
+
+[Install Key]
+ Verification index = 0
+ Target Index = 2
+ # FIXME: Adjust path here
+ File = "/path/to/cst-3.3.1/crts/IMG1_1_sha256_4096_65537_v3_usr_crt.pem"
+
+[Authenticate Data]
+ Verification index = 2
+ # FIXME: Adjust start (first column) and size (third column) here
+ Blocks = 0x7e0fc0 0x0 0x306f0 "flash.bin"
diff --git a/doc/imx/habv4/guides/mx8m_spl_secure_boot.txt b/doc/imx/habv4/guides/mx8m_spl_secure_boot.txt
new file mode 100644
index 0000000..747f7cd
--- /dev/null
+++ b/doc/imx/habv4/guides/mx8m_spl_secure_boot.txt
@@ -0,0 +1,265 @@
+ +=========================================================+
+ + i.MX8M U-Boot HABv4 Secure Boot guide for SPL targets +
+ +=========================================================+
+
+1. HABv4 secure boot process
+-----------------------------
+
+This document is an addendum of mx6_mx7_spl_secure_boot.txt guide describing
+a step-by-step procedure on how to sign and securely boot an U-Boot image for
+SPL targets on i.MX8M, i.MX8M Mini, i.MX8M Nano, i.MX8M Plus.
+
+Details about HAB can be found in the application note AN4581[1] and in the
+introduction_habv4.txt document.
+
+1.1 Building a SPL target supporting secure boot
+-------------------------------------------------
+
+The U-Boot build for i.MX8M SoC makes use of Second Program Loader (SPL)
+support, fitImage support and custom i.MX8M specific flash.bin container.
+This leads to a generation of multiple intermediate build artifacts, the
+U-Boot SPL, U-Boot binary, DT blob. These later two artifacts are bundled
+with external ATF BL31 blob to form a fitImage. The fitImage is bundled
+with SPL and external DDR and optional HDMI PHY initialization blobs to
+form the final flash.bin container. The HABv4 can be used to authenticate
+all of the input binaries separately.
+
+Out of reset the ROM code authenticates the SPL and PHY initialization
+blobs, combination of which is responsible for initializing essential
+features such as DDR, UART, PMIC and clock enablement. Once the DDR is
+available, the SPL code loads the secondary fitImage to its specific
+address and call the HAB APIs to extend the root of trust on its
+components.
+
+The U-Boot SPL provides support to secure boot configuration and also
+provide access to the HAB APIs exposed by the ROM vector table, the
+U-Boot provides access to HAB APIs via SMC calls to ATF. The support
+is enabled by selecting the CONFIG_IMX_HAB option.
+
+When built with this configuration the U-Boot correctly pads combined
+SPL and PHY initialization blob image, called u-boot-spl-ddr.bin, by
+aligning to the next 0xC00 address, so the CSF signature data generated
+by CST can be concatenated to the image.
+
+The U-Boot also reserves space in the fitImage binary (u-boot.itb) between
+the fitImage tree and external blobs included in it, so it can be used to
+inject IVT and CST signatures used by SPL HAB calls to authenticate the
+fitImage components.
+
+The diagram below illustrate a signed SPL combined with DDR PHY
+initialization firmware blobs part of flash.bin container layout.
+This part is loaded to memory address ( CONFIG_SPL_TEXT_BASE - 0x40 ) and
+authenticated the BootROM. The reason for the offset is so that the *entry
+would be at memory address CONFIG_SPL_TEXT_BASE when BootROM executes the
+code within it:
+
+ ------- +-----------------------------+ <-- *start
+ ^ | Image Vector Table |
+ | | (0x20 bytes) |
+ | +-----------------------------+ <-- *boot_data
+ | | Boot Data |
+ | +-----------------------------+
+ | | Padding |
+ Signed | | to 0x40 bytes from *start |
+ Data | +-----------------------------+ <-- *entry
+ | | |
+ | | SPL combined with DDR PHY |
+ | | initialization blobs |
+ | | (u-boot-spl-ddr.bin) |
+ | | |
+ | +-----------------------------+
+ v | Padding |
+ ------- +-----------------------------+ <-- *csf
+ | |
+ | Command Sequence File (CSF) |
+ | |
+ +-----------------------------+
+ | Padding (optional) |
+ +-----------------------------+
+
+The diagram below illustrate a signed U-Boot binary, DT blob and external
+ATF BL31 blob combined to form fitImage part of flash.bin container layout.
+The *load_address is derived from CONFIG_SYS_TEXT_BASE such that the U-Boot
+binary *start is placed exactly at CONFIG_SPL_TEXT_BASE in DRAM, however the
+SPL moves the fitImage tree further to location:
+ *load_address = CONFIG_SPL_TEXT_BASE - CONFIG_FIT_EXTERNAL_OFFSET (=12kiB) -
+ 512 Byte sector - sizeof(mkimage header)
+
+ ------- +-----------------------------+ <-- *load_address
+ ^ | |
+ | | fitImage tree |
+ | | with external data at |
+ | | offset 12 kiB from tree |
+ | | (cca. 1 kiB) |
+ Signed | | |
+ .----- Tree | +-----------------------------+
+ | Data | | Padding to next 4k aligned |
+ | | | from *load_address |
+ | | +-----------------------------+ <-- *ivt
+ | | | Image Vector Table |
+ | v | (0x20 bytes) |
+ | ------- +-----------------------------+ <-- *csf
+ | | Command Sequence File (CSF) |
+ | | for all signed entries in |
+ >--------------->| the fitImage, tree and data |
+ | | (cca 6-7 kiB) |
+ | +-----------------------------+
+ | | Padding to 12 kiB offset |
+ | | from *load_address |
+ | ------- +-----------------------------+ <-- *start
+ | ^ | |
+ | Signed | | |
+ |---- Payload | | U-Boot external data blob |
+ | Data | | |
+ | v | |
+ | ------- +-----------------------------+
+ | | Padding to 4 Bytes |
+ | ------- +-----------------------------+
+ | ^ | |
+ | Signed | | |
+ |---- Payload | | ATF external data blob |
+ | Data | | |
+ | v | |
+ | ------- +-----------------------------+
+ | | Padding to 4 Bytes |
+ | ------- +-----------------------------+
+ | ^ | |
+ | Signed | | |
+ '---- Payload | | DTB external data blob |
+ Data | | |
+ v | |
+ ------- +-----------------------------+
+
+The diagram below illustrate a combined flash.bin container layout:
+
+ +-----------------------------+
+ | Signed SPL part |
+ +-----------------------------+
+ | Signed fitImage part |
+ +-----------------------------+
+
+1.2 Enabling the secure boot support
+-------------------------------------
+
+The first step is to generate an U-Boot image supporting the HAB features
+mentioned above, this can be achieved by adding CONFIG_IMX_HAB to the
+build configuration:
+
+- Defconfig:
+
+ CONFIG_IMX_HAB=y
+
+- Kconfig:
+
+ ARM architecture -> Support i.MX HAB features
+
+1.3 Signing the images
+-----------------------
+
+The CSF contains all the commands that the HAB executes during the secure
+boot. These commands instruct the HAB code on which memory areas of the image
+to authenticate, which keys to install, use and etc.
+
+CSF examples are available under doc/imx/habv4/csf_examples/ directory.
+
+CSF "Blocks" line for csf_spl.txt can be generated as follows:
+
+```
+spl_block_base=$(printf "0x%x" $(( $(sed -n "/CONFIG_SPL_TEXT_BASE=/ s@.*=@@p" .config) - 0x40)) )
+spl_block_size=$(printf "0x%x" $(stat -tc %s u-boot-spl-ddr.bin))
+sed -i "/Blocks = / s@.*@ Blocks = $spl_block_base 0x0 $spl_block_size \"flash.bin\"@" csf_spl.txt
+```
+
+The resulting line looks as follows:
+```
+ Blocks = 0x7e0fc0 0x0 0x306f0 "flash.bin"
+```
+
+The columns mean:
+ - CONFIG_SPL_TEXT_BASE - 0x40 -- Start address of signed data, in DRAM
+ - 0x0 -- Start address of signed data, in "flash.bin"
+ - 0x306f0 -- Length of signed data, in "flash.bin"
+ - Filename -- "flash.bin"
+
+To generate signature for the SPL part of flash.bin container, use CST:
+```
+cst -i csf_spl.tmp -o csf_spl.bin
+```
+
+The newly generated CST blob has to be patched into existing flash.bin
+container. Conveniently, flash.bin IVT contains physical address of the
+CSF blob. Remember, the SPL part of flash.bin container is loaded by the
+BootROM at CONFIG_SPL_TEXT_BASE - 0x40 , so the offset of CSF blob in
+the fitImage can be calculated and inserted into the flash.bin in the
+correct location as follows:
+```
+# offset = IVT_HEADER[6 = CSF address] - CONFIG_SPL_TEXT_BASE - 0x40
+spl_csf_offset=$(xxd -s 24 -l 4 -e flash.bin | cut -d " " -f 2 | sed "s@^@0x@")
+spl_bin_offset=$(xxd -s 4 -l 4 -e flash.bin | cut -d " " -f 2 | sed "s@^@0x@")
+spl_dd_offset=$((${spl_csf_offset} - ${spl_bin_offset} + 0x40))
+dd if=csf_spl.bin of=flash.bin bs=1 seek=${spl_dd_offset} conv=notrunc
+```
+
+CSF "Blocks" line for csf_fit.txt can be generated as follows:
+```
+# fitImage tree
+fit_block_base=$(printf "0x%x" $(( $(sed -n "/CONFIG_SYS_TEXT_BASE=/ s@.*=@@p" .config) - $(sed -n "/CONFIG_FIT_EXTERNAL_OFFSET=/ s@.*=@@p" .config) - 0x200 - 0x40)) )
+fit_block_offset=$(printf "0x%s" $(fdtget -t x u-boot.dtb /binman/imx-boot/uboot offset))
+fit_block_size=$(printf "0x%x" $(( ( $(fdtdump u-boot.itb 2>/dev/null | sed -n "/^...totalsize:/ s@.*\(0x[0-9a-f]\+\).*@\1@p") + 0x1000 - 0x1 ) & ~(0x1000 - 0x1) + 0x20 )) )
+sed -i "/Blocks = / s@.*@ Blocks = $fit_block_base $fit_block_offset $fit_block_size \"flash.bin\", \\\\@" csf_fit.tmp
+
+# U-Boot
+uboot_block_base=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/uboot load))
+uboot_block_offset=$(printf "0x%x" $(( $(printf "0x%s" $(fdtget -t x u-boot.itb /images/uboot data-position)) + ${fit_block_offset} )))
+uboot_block_size=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/uboot data-size))
+sed -i "/0xuuuu/ s@.*@ $uboot_block_base $uboot_block_offset $uboot_block_size \"flash.bin\", \\\\@" csf_fit.tmp
+
+# ATF
+atf_block_base=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/atf load))
+atf_block_offset=$(printf "0x%x" $(( $(printf "0x%s" $(fdtget -t x u-boot.itb /images/atf data-position)) + ${fit_block_offset} )))
+atf_block_size=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/atf data-size))
+sed -i "/0xaaaa/ s@.*@ $atf_block_base $atf_block_offset $atf_block_size \"flash.bin\", \\\\@" csf_fit.tmp
+
+# DTB
+dtb_block_base=$(printf "0x%x" $(( ${uboot_block_base} + ${uboot_block_size} )))
+dtb_block_offset=$(printf "0x%x" $(( $(printf "0x%s" $(fdtget -t x u-boot.itb /images/fdt-1 data-position)) + ${fit_block_offset} )))
+dtb_block_size=$(printf "0x%s" $(fdtget -t x u-boot.itb /images/fdt-1 data-size))
+sed -i "/0xdddd/ s@.*@ $dtb_block_base $dtb_block_offset $dtb_block_size \"flash.bin\"@" csf_fit.tmp
+```
+
+The fitImage part of flash.bin requires separate IVT. Generate the IVT and
+patch it into the correct aligned location of flash.bin as follows:
+```
+# IVT
+ivt_ptr_base=$(printf "%08x" ${fit_block_base} | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@")
+ivt_block_base=$(printf "%08x" $(( ${fit_block_base} + ${fit_block_size} - 0x20 )) | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@")
+csf_block_base=$(printf "%08x" $(( ${fit_block_base} + ${fit_block_size} )) | sed "s@\(..\)\(..\)\(..\)\(..\)@0x\4\3\2\1@")
+ivt_block_offset=$((${fit_block_offset} + ${fit_block_size} - 0x20))
+csf_block_offset=$((${ivt_block_offset} + 0x20))
+
+echo "0xd1002041 ${ivt_ptr_base} 0x00000000 0x00000000 0x00000000 ${ivt_block_base} ${csf_block_base} 0x00000000" | xxd -r -p > ivt.bin
+dd if=ivt.bin of=flash.bin bs=1 seek=${ivt_block_offset} conv=notrunc
+
+To generate CSF signature for the fitImage part of flash.bin container, use CST:
+```
+cst -i csf_fit.tmp -o csf_fit.bin
+```
+
+Finally, patch the CSF signature into the fitImage right past the IVT:
+```
+dd if=csf_fit.bin of=flash.bin bs=1 seek=${csf_block_offset} conv=notrunc
+```
+
+The entire script is available in doc/imx/habv4/csf_examples/mx8m/csf.sh
+
+1.4 Closing the device
+-----------------------
+
+The procedure for closing the device is similar as in Non-SPL targets, for a
+complete procedure please refer to section "1.5 Programming SRK Hash" in
+mx6_mx7_secure_boot.txt document available under doc/imx/habv4/guides/
+directory.
+
+References:
+[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using
+ HABv4" - Rev 2.
diff --git a/doc/usage/cmd/gpio.rst b/doc/usage/cmd/gpio.rst
index f6a5668..ee90213 100644
--- a/doc/usage/cmd/gpio.rst
+++ b/doc/usage/cmd/gpio.rst
@@ -45,6 +45,31 @@ gpio status
Display the status of one or multiple GPIOs. By default only claimed GPIOs
are displayed.
+gpio status command output fields are::
+
+ <name>: <function>: <value> [x] <label>
+
+*function* can take the following values:
+
+output
+ pin configured in gpio output, *value* indicates the pin's level
+
+input
+ pin configured in gpio input, *value* indicates the pin's level
+
+func
+ pin configured in alternate function, followed by *label*
+ which shows pinmuxing label.
+
+unused
+ pin not configured
+
+*[x]* or *[ ]* indicate respectively if the gpio is used or not.
+
+*label* shows the gpio label.
+
+Parameters
+----------
-a
Display GPIOs irrespective of being claimed.
@@ -77,6 +102,23 @@ Switch the status of a GPIO::
=> echo $myvar
0
+Show the GPIO status::
+
+ => gpio status
+ Bank GPIOA:
+ GPIOA1: func rgmii-0
+ GPIOA2: func rgmii-0
+ GPIOA7: func rgmii-0
+ GPIOA10: output: 0 [x] hdmi-transmitter@39.reset-gpios
+ GPIOA13: output: 1 [x] red.gpios
+
+ Bank GPIOB:
+ GPIOB0: func rgmii-0
+ GPIOB1: func rgmii-0
+ GPIOB2: func uart4-0
+ GPIOB7: input: 0 [x] mmc@58005000.cd-gpios
+ GPIOB11: func rgmii-0
+
Configuration
-------------
diff --git a/doc/usage/cmd/tftpput.rst b/doc/usage/cmd/tftpput.rst
new file mode 100644
index 0000000..52ba7b1
--- /dev/null
+++ b/doc/usage/cmd/tftpput.rst
@@ -0,0 +1,87 @@
+.. SPDX-License-Identifier: GPL-2.0+:
+
+tftpput command
+===============
+
+Synopsis
+--------
+
+::
+
+ tftpput address size [[hostIPaddr:]filename]
+
+Description
+-----------
+
+The tftpput command is used to transfer a file to a TFTP server.
+
+By default the destination port is 69 and the source port is pseudo-random.
+If CONFIG_TFTP_PORT=y, the environment variable *tftpsrcp* can be used to set
+the source port and the environment variable *tftpdstp* can be used to set
+the destination port.
+
+address
+ memory address where the data starts
+
+size
+ number of bytes to be transferred
+
+hostIPaddr
+ IP address of the TFTP server, defaults to the value of environment
+ variable *serverip*
+
+filename
+ path of the file to be written. If not provided, the client's IP address is
+ used to construct a default file name, e.g. C0.A8.00.28.img for IP address
+ 192.168.0.40.
+
+Example
+-------
+
+In the example the following steps are executed:
+
+* setup client network address
+* load a file from the SD-card
+* send the file via TFTP to a server
+
+::
+
+ => setenv autoload no
+ => dhcp
+ BOOTP broadcast 1
+ DHCP client bound to address 192.168.1.40 (7 ms)
+ => load mmc 0:1 $loadaddr test.txt
+ 260096 bytes read in 13 ms (19.1 MiB/s)
+ => tftpput $loadaddr $filesize 192.168.1.3:upload/test.txt
+ Using ethernet@1c30000 device
+ TFTP to server 192.168.1.3; our IP address is 192.168.1.40
+ Filename 'upload/test.txt'.
+ Save address: 0x42000000
+ Save size: 0x3f800
+ Saving: #################
+ 4.4 MiB/s
+ done
+ Bytes transferred = 260096 (3f800 hex)
+ =>
+
+Configuration
+-------------
+
+The command is only available if CONFIG_CMD_TFTPPUT=y.
+
+CONFIG_TFTP_BLOCKSIZE defines the size of the TFTP blocks sent. It defaults
+to 1468 matching an ethernet MTU of 1500.
+
+If CONFIG_TFTP_PORT=y, the environment variables *tftpsrcp* and *tftpdstp* can
+be used to set the source and the destination ports.
+
+CONFIG_TFTP_WINDOWSIZE can be used to set the TFTP window size of transmits
+after which an ACK response is required. The window size defaults to 1.
+
+If CONFIG_TFTP_TSIZE=y, the progress bar is limited to 50 '#' characters.
+Otherwise an '#' is written per UDP package which may decrease performance.
+
+Return value
+------------
+
+The return value $? is 0 (true) on success and 1 (false) otherwise.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 73966c6..0fda121 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -66,6 +66,7 @@ Shell commands
cmd/scp03
cmd/setexpr
cmd/size
+ cmd/tftpput
cmd/true
cmd/ums
cmd/wdt
generated by cgit v1.1 at 2024-11-17 12:40:49 +0000