1 /** @page endianness About endianness
3 OpenOCD has to potentially deal with different endianness between:
4 - the host PC endianness;
5 - the data endianness during communication between host and adapter;
6 - the target CPU endianness.
8 The whole OpenOCD code should be written to handle any endianness
9 mismatch and should run on either little and big endian hosts.
11 Big-endian host PC are becoming less and less common since Apple™ has
12 switched away from big-endian PowerPC™ in favor of little-endian intel
15 The lack of commercial big-endian hosts makes hard testing OpenOCD correctness
16 on big-endian hosts. Running OpenOCD on low-cost commercial routers based on
17 big-endian MIPS is possible, but it's tricky to properly setup the system and
18 the cross-compiling environment.
20 In next sections there are two example on how to compile and test OpenOCD in an
21 emulated big-endian environment.
24 @section endianness_helpers OpenOCD API for handling endianness
26 Use the following OpenOCD API to handle endianness conversions:
27 - host endianness to/from little endian:
28 - le_to_h_u64(), le_to_h_u32(), le_to_h_u16();
29 - h_u64_to_le(), h_u32_to_le(), h_u16_to_le();
30 - buf_get_u32(), buf_get_u64();
31 - buf_set_u32(), buf_set_u64();
32 - host endianness to/from big endian:
33 - be_to_h_u64(), be_to_h_u32(), be_to_h_u16();
34 - h_u64_to_be(), h_u32_to_be(), h_u16_to_be();
35 - host endianness to/from target endianness:
36 - target_read_u64(), target_read_u32(), target_read_u16();
37 - target_write_u64(), target_write_u32(), target_write_u16();
38 - target_write_phys_u64(), target_write_phys_u32(), target_write_phys_u16();
39 - target_buffer_get_u64(), target_buffer_get_u32(), target_buffer_get_u24(), target_buffer_get_u16();
40 - target_buffer_set_u64(), target_buffer_set_u32(), target_buffer_set_u24(), target_buffer_set_u16();
42 - buf_bswap32(), buf_bswap16().
45 @section endianness_docker Use dockers to run different endianness
48 Docker can run a full Linux image that includes the toolchain through QEMU
50 By selecting a big-endian image, it's possible to compile and execute OpenOCD
52 There are, so far, not many options for big-endian images; s390x is one of the
59 - download the big-endian image;
60 - run the image in docker;
61 - download, in the image, the OpenOCD code to test;
62 - recompile OpenOCD code in the image;
63 - run OpenOCD binary in the image.
65 From https://github.com/multiarch/qemu-user-static
68 docker run --rm -t s390x/ubuntu bash
72 @section endianness_qemu Use buildroot and QEMU to run different endianness
74 QEMU User Mode Emulation is an efficient method to launch, on host's CPU,
75 applications compiled for another CPU and/or for different endianness.
76 It works either on Linux and BSD. More info available on
77 https://www.qemu.org/docs/master/user/index.html
79 With QEMU User Mode Emulation is thus possible running, on a commonly available
80 little-endian X86 Linux host, OpenOCD compiled for a big-endian host.
82 The following example will show how to use buildroot to:
83 - build big-endian toolchain and libraries;
84 - compile OpenOCD for big-endian;
85 - run the big-endian OpenOCD on little-endian Linux PC.
87 The example will use ARM Cortex-A7 big-endian only because I personally feel
88 comfortable reading ARM assembly during debug. User can select other CPU
89 architectures, as this does not impact the result.
91 A similar method can be used to test OpenOCD compiled for 32 vs 64 bit host.
94 - the version of autotools locally installer in your Linux host can be
95 incompatible with the version of autotools used by buildroot. This can cause
96 the build to fail if buildroot has to run its autotools on a partially
97 configured OpenOCD folder. Use either a clean copy of OpenOCD code in 2., or
98 run "./bootstrap" in OpenOCD folder to prevent buildroot from using its own
100 - the configuration tool in 4. and 5. matches the version of OpenOCD used by
101 buildroot. Some new driver could be not listed in. OpenOCD will build every
102 driver that is not disabled and with satisfied dependencies. If the driver
103 you plan to use is not listed, try a first build and check OpenOCD with
104 command "adapter list", then try to hack the buildroot files Config.in and
105 openocd.mk in folder package/openocd/ and use "make openocd-reconfigure" to
106 rerun the build starting with configuration;
107 - using pre-built toolchains, you need 2GB of disk space for buildroot build.
108 To also rebuild the toolchains you will need ~5GB and much longer time for
109 the first build (it takes ~2 hour on my crap 10+ years old laptop);
110 - you need to install few tools for buildroot dependency, listed in
111 https://buildroot.org/downloads/manual/manual.html#requirement ;
112 - you need to install qemu-armeb. On Arch Linux it's in package qemu-arch-extra;
113 on Ubuntu/debian it's packaged in qemu-user.
114 Buildroot can also be configured to build qemu for the host, if you prefer,
115 by enabling BR2_PACKAGE_HOST_QEMU_LINUX_USER_MODE, but this takes longer
117 - don't use qemu-system-arm, as it emulates a complete system and requires a
118 fully bootable ARM image;
119 - while QEMU User Mode Emulation is available for both Linux and BSD, buildroot
120 only builds binaries for Linux target. This example can only be used with
121 Linux hosts emulating the Linux target.
124 Steps to run big-endian OpenOCD on little-endian host Linux PC:
126 1. Get buildroot source. Today's latest version is "2022.02":
128 wget https://buildroot.org/downloads/buildroot-2022.02.tar.xz
129 tar xf buildroot-2022.02.tar.xz
133 2. Override the source repo for OpenOCD in order to build your own code version
134 in place of the default OpenOCD release version:
136 echo OPENOCD_OVERRIDE_SRCDIR=/home/me/openocd.git >> local.mk
139 3. Copy default config for OpenOCD big-endian. This used:
140 - ARM Cortex-A7 big-endian target,
141 - external Linaro armeb toolchain (to speed up first build),
142 - OpenOCD all configure options enabled.
145 cp $OPENOCD_OVERRIDE_SRCDIR/contrib/buildroot/openocd_be_defconfig configs/
148 4. Configure buildroot with default config for OpenOCD big-endian:
150 make openocd_be_defconfig
153 5. Optional, change buildroot configuration:
157 These are the options selected with default config for OpenOCD big-endian:
160 Target Architecture --->
162 Target Architecture Variant --->
169 Toolchain origin --->
170 Toolchain to be downloaded and installed
172 Hardware handling --->
174 All adapters selected
178 6. Build (and take a long coffee break ...):
183 7. Execute big-endian OpenOCD:
186 qemu-armeb -cpu cortex-a7 -L . usr/bin/openocd -s usr/share/openocd/scripts/ -f board/st_nucleo_f4.cfg
189 8. Optional, to rebuild after any source code modification in ${OPENOCD_OVERRIDE_SRCDIR}:
196 This file contains the @ref endianness page.