This is an automated email from Gerrit.
"Antonio Borneo <borneo.anto...@gmail.com>" just uploaded a new patch set to
Gerrit, which you can find at https://review.openocd.org/c/openocd/+/6968
-- gerrit
commit de5ec470927f18217e022048ba0bb2c0f0df2ad5
Author: Antonio Borneo <borneo.anto...@gmail.com>
Date: Thu May 5 17:23:49 2022 +0200
doc: how to use QEMU to test big-endian build
Document the process of using buildroot to build a big-endian
binary of OpenOCD and using QEMU User Mode Emulation for running
the big-endian binary on a little-endian host PC.
Change-Id: Ic5fe26e353a4cf69e57af3c23ae7fa4b25347b2b
Signed-off-by: Antonio Borneo <borneo.anto...@gmail.com>
diff --git a/doc/manual/endianness.txt b/doc/manual/endianness.txt
new file mode 100644
index 0000000000..e71bcfa696
--- /dev/null
+++ b/doc/manual/endianness.txt
@@ -0,0 +1,121 @@
+/** @page endianness About endianness
+
+OpenOCD has to potentially deal with different endianness between:
+- the host PC endianness;
+- the data endianness during communication between host and adapter;
+- the target CPU endianness.
+
+The whole OpenOCD code should be written to handle any endianness
+mismatch and should run on either little and big endian hosts.
+
+
+@section endianness_helpers OpenOCD API for handling endianness
+
+This section needs to be expanded to describe OpenOCD API for handling
+endianness, e.g.:
+- le_to_h_u64(), le_to_h_u32(), le_to_h_u16();
+- be_to_h_u64(), be_to_h_u32(), be_to_h_u16();
+- h_u64_to_le(), h_u32_to_le(), h_u16_to_le();
+- h_u64_to_be(), h_u32_to_be(), h_u16_to_be();
+- buf_bswap32(), buf_bswap16();
+- ... .
+
+
+@section endianness_qemu Use QEMU to run different endianness
+
+Big-endian host PC are becoming less and less common since Apple™ has
+switched away from big-endian PowerPC™ in favor of little-endian intel
+X86™.
+
+The lack of commercial big-endian hosts makes hard testing OpenOCD correctness
+on big-endian hosts. Running OpenOCD on a low-cost commercial routers based on
+big-endian MIPS is possible, but it's tricky to properly setup the system and
+the cross-compiling environment.
+
+QEMU User Mode Emulation is an efficient method to launch, on host's CPU,
+applications compiled for another CPU and/or for different endianness.
+It works either on Linux and BSD. More info available on
+https://www.qemu.org/docs/master/user/index.html
+
+With QEMU User Mode Emulation is thus possible running, on a commonly available
+little-endian X86 Linux host, OpenOCD compiled for a big-endian host.
+
+The following example will show how to use buildroot to:
+- build big-endian toolchain and libraries;
+- compile OpenOCD for big-endian;
+- run the big-endian OpenOCD on little-endian Linux PC.
+
+The example will use ARM Cortex-A7 big-endian only because I personally feel
+comfortable reading ARM assembly during debug. User can select other CPU
+architectures, as this does not impact the result.
+
+A similar method can be used to test OpenOCD compiled for 32 vs 64 bit host.
+
+@notes
+- OpenOCD source code in 3) must have "./bootstrap" already run;
+- you need ~5GB disk space for buildroot build;
+- the first build takes ~2 hour on my crap 10+ years old laptop;
+- you need to install few tools for buildroot dependency, listed in
+ https://buildroot.org/downloads/manual/manual.html#requirement ;
+- you need to install qemu-armeb. On Arch Linux it's in package
qemu-arch-extra;
+ on Ubuntu/debian it's packaged in qemu-user.
+ Buildroot can also be configured to build qemu for the host, if you prefer,
+ by enabling BR2_PACKAGE_HOST_QEMU_LINUX_USER_MODE, but this takes longer
+ compile time;
+- don't use qemu-system-arm, as it emulates a complete system and requires a
+ fully bootable ARM build.
+
+
+Steps to run big-endian OpenOCD on little-endian host Linux PC:
+
+1. Get buildroot source. Today's latest version is "2022.02":
+ @code{.unparsed}
+ wget https://buildroot.org/downloads/buildroot-2022.02.tar.xz
+ tar xf buildroot-2022.02.tar.xz
+ cd buildroot-2022.02
+ @endcode
+
+2. Configure buildroot:
+ @code{.unparsed}
+ make menuconfig
+ @endcode
+ Select the following options:
+ @code{.unparsed}
+ Target options --->
+ Target Architecture --->
+ ARM (big endian)
+ Target Architecture Variant --->
+ cortex-A7
+ Target packages --->
+ Hardware handling --->
+ openocd
+ Select any adapter you need
+ @endcode
+ Save and exit
+
+3. Override the source repo for OpenOCD in order to build your own code version
+ in place of the default OpenOCD release version:
+ @code{.unparsed}
+ echo OPENOCD_OVERRIDE_SRCDIR=/home/me/openocd.git >> local.mk
+ @endcode
+
+4. Build (and take a long coffee break ...):
+ @code{.unparsed}
+ make openocd
+ @endcode
+
+5. Execute big-endian OpenOCD:
+ @code{.unparsed}
+ cd output/target
+ qemu-armeb -cpu cortex-a7 -L . usr/bin/openocd -s
usr/share/openocd/scripts/ -f board/st_nucleo_f4.cfg
+ @endcode
+
+6. Optional, to rebuild after any source code modification in
${OPENOCD_OVERRIDE_SRCDIR}:
+ @code{.unparsed}
+ make openocd-rebuild
+ @endcode
+
+ */
+/** @file
+This file contains the @ref endianness page.
+ */
diff --git a/doc/manual/main.txt b/doc/manual/main.txt
index 14c64c2e76..c28fbe2288 100644
--- a/doc/manual/main.txt
+++ b/doc/manual/main.txt
@@ -19,6 +19,8 @@ check the mailing list archives to find the status of your
feature (or bug).
- The @subpage bugs page contains the content of the BUGS file, which
provides instructions for submitting bug reports to the maintainers.
- The @subpage releases page describes the project's release process.
+- The @subpage endianness provides hints about writing and testing
+ endianness independent code for OpenOCD.
@ref primer provide introductory materials for new developers on various
specific topics.
--
