Repository : ssh://git@diktynna/doc

On branch : main

commit 2af2f27f578b1f4387dec15a3899df8fd637e48b Merge: 00a809ee 39c2ec24 Author: Sven Eckelmann sven@narfation.org Date: Mon Nov 14 10:14:27 2022 +0100

Merge branch 'backup-redmine/2022-11-14'

2af2f27f578b1f4387dec15a3899df8fd637e48b devtools/Kernel_debugging_with_kgdb.rst | 412 ++++++++++++-------------------- open-mesh/Download.rst | 26 +- 2 files changed, 165 insertions(+), 273 deletions(-)

diff --cc devtools/Kernel_debugging_with_kgdb.rst index ada2d42b,00000000..feab49a1 mode 100644,000000..100644 --- a/devtools/Kernel_debugging_with_kgdb.rst +++ b/devtools/Kernel_debugging_with_kgdb.rst @@@ -1,454 -1,0 +1,344 @@@ +.. SPDX-License-Identifier: GPL-2.0 + +OpenWrt KGDB +============ + - As shown in the :doc:`Kernel_debugging_with_qemu's_GDB_server` documentation, it - is easy to debug Linux kernel in an :doc:`emulated system <OpenWrt_in_QEMU>`. ++As shown in the :doc:`Kernel_debugging_with_qemu's_GDB_server`documentation, it ++is easy to debug the Linux kernel in an :doc:`emulated system <OpenWrt_in_QEMU>`. +But some problems might only be reproducible on actual hardware - :doc:`connected to the emulation setup <Mixing_VM_with_gluon_hardware>`. It ++(:doc:`connected to the emulation setup <Mixing_VM_with_gluon_hardware>`). It +is therefore sometimes necessary to debug a whole system. + +In best case, the system can be :doc:`debugged using +JTAG <Kernel_debugging_over_JTAG>`. But this +is often not possible and an in-kernel gdb remote stub like +`KGDB https://www.kernel.org/doc/html/latest/dev-tools/kgdb.html`__ +has to be used. The only requirement it has on the actual board is a +simple serial console with poll_{get,put}_char() support. + +Preparing OpenWrt +----------------- + +Turning off watchdog +~~~~~~~~~~~~~~~~~~~~ + +Most CPUs have some kind of watchdog integrated. They can often be +turned off and are often inactive when the watchdog driver is not +loaded. For example, ath79 can be build without the internal watchdog +support by changing in ``target/linux/ath79/config-*``: + +.. code-block:: diff + + -CONFIG_ATH79_WDT=y + +# CONFIG_ATH79_WDT is not set + +Unfortunately, there are also external watchdog chips which cannot be +turned off. They have to be manually triggered regularly during the +debugging process to prevent a sudden reboot. The details depend on the +actual hardware but it often ends up in writing to a specific (GPIO +control/set/clear) register. An example how to manually trigger an GPIO +connected watchdog manually can be found in +:ref:`GDB Linux snippets <devtools-gdb-linux-snippets-Working-with-external-Watchdog-over-GPIO>` + ++It is also possible to stop the watchdog service at runtime without ++disabling the driver. This should work for many optional watchdogs in ++SoCs: ++ ++.. code-block:: sh ++ ++ ubus call system watchdog '{"magicclose":true}' ++ ubus call system watchdog '{"stop":true}' ++ +Enabling KGDB in kernel +~~~~~~~~~~~~~~~~~~~~~~~ + - The actual kernel gdbstub cannot be enabled via OpenWrt's .config. - Instead the actual configuration has to be set in the target - configuration: ++OpenWrt must be modified slightly to expose the kernel gdbstub ++(``CONFIG_KERNEL_KGDB``): + - :: ++.. code-block:: diff + - # CONFIG_STRICT_KERNEL_RWX is not set - CONFIG_FRAME_POINTER=y - CONFIG_KGDB=y - CONFIG_KGDB_SERIAL_CONSOLE=y - CONFIG_DEBUG_INFO=y - CONFIG_DEBUG_INFO_DWARF4=y - # CONFIG_DEBUG_INFO_REDUCED is not set - CONFIG_GDB_SCRIPTS=y ++ From: Sven Eckelmann sven@narfation.org ++ Date: Thu, 13 Oct 2022 16:40:21 +0200 ++ Subject: openwrt: Add support for easily selectable kernel debugger support + - # optional: to allow activation of kgdb over serial by agent-proxy - # instead of manually triggering it over /proc/sysrq-trigger - CONFIG_MAGIC_SYSRQ_SERIAL=y ++ When enabling this KERNEL_KGDB, make sure to clean some packages to make ++ sure that they are compiled with the correct settings: + - For x86-64, the change (mostly created using make kernel_menuconfig) - would be: ++ make toolchain/gdb/clean ++ make toolchain/gdb/compile -j$(nproc || echo 1) ++ make target/linux/clean ++ make -j$(nproc || echo 1) + - .. code-block:: diff ++ The session can (after initializing agent-proxy) on serial via: + - diff --git a/target/linux/x86/config-5.4 b/target/linux/x86/config-5.4 - index 6676f9501a..2518c8f57b 100644 - --- a/target/linux/x86/config-5.4 - +++ b/target/linux/x86/config-5.4 - @@ -78,6 +78,7 @@ CONFIG_COMMON_CLK=y - CONFIG_COMPAT_32=y - CONFIG_COMPAT_32BIT_TIME=y - # CONFIG_COMPAT_VDSO is not set - +CONFIG_CONSOLE_POLL=y - CONFIG_CONSOLE_TRANSLATIONS=y - # CONFIG_CPU5_WDT is not set - CONFIG_CPU_FREQ=y - @@ -116,6 +117,9 @@ CONFIG_DCACHE_WORD_ACCESS=y - # CONFIG_DCDBAS is not set - # CONFIG_DEBUG_BOOT_PARAMS is not set - # CONFIG_DEBUG_ENTRY is not set - +CONFIG_DEBUG_INFO=y - +CONFIG_DEBUG_INFO_DWARF4=y - +# CONFIG_DEBUG_INFO_REDUCED is not set - CONFIG_DEBUG_MEMORY_INIT=y - CONFIG_DEBUG_MISC=y - # CONFIG_DEBUG_NMI_SELFTEST is not set - @@ -161,6 +165,7 @@ CONFIG_FUSION=y - CONFIG_FUSION_MAX_SGE=128 - CONFIG_FUSION_SPI=y - CONFIG_FW_LOADER_PAGED_BUF=y - +CONFIG_GDB_SCRIPTS=y - CONFIG_GENERIC_ALLOCATOR=y - CONFIG_GENERIC_BUG=y - CONFIG_GENERIC_CLOCKEVENTS=y - @@ -306,6 +311,11 @@ CONFIG_KALLSYMS=y - CONFIG_KEXEC=y - CONFIG_KEXEC_CORE=y - CONFIG_KEYBOARD_ATKBD=y - +CONFIG_KGDB=y - +# CONFIG_KGDB_KDB is not set - +# CONFIG_KGDB_LOW_LEVEL_TRAP is not set - +CONFIG_KGDB_SERIAL_CONSOLE=y - +# CONFIG_KGDB_TESTS is not set - # CONFIG_LEDS_CLEVO_MAIL is not set - CONFIG_LOCK_DEBUGGING_SUPPORT=y - # CONFIG_M486 is not set - @@ -314,6 +324,8 @@ CONFIG_M586MMX=y - # CONFIG_M586TSC is not set - # CONFIG_M686 is not set - # CONFIG_MACHZ_WDT is not set - +CONFIG_MAGIC_SYSRQ=y - +CONFIG_MAGIC_SYSRQ_SERIAL=y - # CONFIG_MATOM is not set - # CONFIG_MCORE2 is not set - # CONFIG_MCRUSOE is not set - @@ -421,6 +433,7 @@ CONFIG_SCx200HR_TIMER=y - # CONFIG_SCx200_GPIO is not set - # CONFIG_SCx200_WDT is not set - CONFIG_SERIAL_8250_PCI=y - +# CONFIG_SERIAL_KGDB_NMI is not set - CONFIG_SERIO=y - CONFIG_SERIO_I8042=y - CONFIG_SERIO_LIBPS2=y - diff --git a/target/linux/x86/image/Makefile b/target/linux/x86/image/Makefile - index f61e4ff802..e8c05c58e5 100644 - --- a/target/linux/x86/image/Makefile - +++ b/target/linux/x86/image/Makefile - @@ -9,7 +9,7 @@ GRUB2_VARIANT = - GRUB_TERMINALS = - GRUB_SERIAL_CONFIG = - GRUB_TERMINAL_CONFIG = - -GRUB_CONSOLE_CMDLINE = - +GRUB_CONSOLE_CMDLINE = nokaslr - - ifneq ($(CONFIG_GRUB_CONSOLE),) - GRUB_CONSOLE_CMDLINE += console=tty0 - - For ath79 (GL.inet AR750 in my case), it would look like: ++ ubus call system watchdog '{"magicclose":true}' ++ ubus call system watchdog '{"stop":true}' + - .. code-block:: diff ++ echo ttyMSM0,115200 > /sys/module/kgdboc/parameters/kgdboc ++ echo g > /proc/sysrq-trigger + - diff --git a/target/linux/ath79/config-5.4 b/target/linux/ath79/config-5.4 - index 60f57692e2..01b66897fe 100644 - --- a/target/linux/ath79/config-5.4 - +++ b/target/linux/ath79/config-5.4 - @@ -25,7 +25,7 @@ CONFIG_ARCH_WANT_DEFAULT_TOPDOWN_MMAP_LAYOUT=y - CONFIG_ARCH_WANT_IPC_PARSE_VERSION=y - CONFIG_AT803X_PHY=y - CONFIG_ATH79=y - -CONFIG_ATH79_WDT=y - +# CONFIG_ATH79_WDT is not set - CONFIG_BLK_MQ_PCI=y - CONFIG_CEVT_R4K=y - CONFIG_CLKDEV_LOOKUP=y - @@ -34,6 +34,8 @@ CONFIG_CMDLINE="rootfstype=squashfs,jffs2" - CONFIG_CMDLINE_BOOL=y - # CONFIG_CMDLINE_OVERRIDE is not set - CONFIG_COMMON_CLK=y - +CONFIG_CONSOLE_POLL=y - +CONFIG_CONSOLE_TRANSLATIONS=y - # CONFIG_COMMON_CLK_BOSTON is not set - CONFIG_COMPAT_32BIT_TIME=y - CONFIG_CPU_BIG_ENDIAN=y - @@ -52,9 +54,13 @@ CONFIG_CPU_SUPPORTS_HIGHMEM=y - CONFIG_CPU_SUPPORTS_MSA=y - CONFIG_CRYPTO_RNG2=y - CONFIG_CSRC_R4K=y - +CONFIG_DEBUG_INFO=y - +CONFIG_DEBUG_INFO_DWARF4=y - +# CONFIG_DEBUG_INFO_REDUCED is not set - CONFIG_DMA_NONCOHERENT=y - CONFIG_DMA_NONCOHERENT_CACHE_SYNC=y - CONFIG_DTC=y - +CONFIG_DUMMY_CONSOLE=y - CONFIG_EARLY_PRINTK=y - CONFIG_EFI_EARLYCON=y - CONFIG_ETHERNET_PACKET_MANGLE=y - @@ -63,6 +69,7 @@ CONFIG_FONT_8x16=y - CONFIG_FONT_AUTOSELECT=y - CONFIG_FONT_SUPPORT=y - CONFIG_FW_LOADER_PAGED_BUF=y - +CONFIG_GDB_SCRIPTS=y - CONFIG_GENERIC_ATOMIC64=y - CONFIG_GENERIC_CLOCKEVENTS=y - CONFIG_GENERIC_CMOS_UPDATE=y - @@ -132,18 +139,27 @@ CONFIG_HAVE_REGS_AND_STACK_ACCESS_API=y - CONFIG_HAVE_RSEQ=y - CONFIG_HAVE_SYSCALL_TRACEPOINTS=y - CONFIG_HAVE_VIRT_CPU_ACCOUNTING_GEN=y - +CONFIG_HW_CONSOLE=y - CONFIG_HZ_PERIODIC=y - CONFIG_IMAGE_CMDLINE_HACK=y - CONFIG_INITRAMFS_SOURCE="" - +CONFIG_INPUT=y - CONFIG_IRQCHIP=y - CONFIG_IRQ_DOMAIN=y - CONFIG_IRQ_FORCED_THREADING=y - CONFIG_IRQ_MIPS_CPU=y - CONFIG_IRQ_WORK=y - +CONFIG_KGDB=y - +# CONFIG_KGDB_KDB is not set - +# CONFIG_KGDB_LOW_LEVEL_TRAP is not set - +CONFIG_KGDB_SERIAL_CONSOLE=y - +# CONFIG_KGDB_TESTS is not set - CONFIG_LEDS_GPIO=y - # CONFIG_LEDS_RESET is not set - CONFIG_LIBFDT=y - CONFIG_LOCK_DEBUGGING_SUPPORT=y - +CONFIG_MAGIC_SYSRQ=y - +CONFIG_MAGIC_SYSRQ_SERIAL=y - CONFIG_MDIO_BITBANG=y - CONFIG_MDIO_BUS=y - CONFIG_MDIO_DEVICE=y - @@ -161,6 +177,7 @@ CONFIG_MIPS_CLOCK_VSYSCALL=y - # CONFIG_MIPS_CMDLINE_FROM_BOOTLOADER is not set - CONFIG_MIPS_CMDLINE_FROM_DTB=y - # CONFIG_MIPS_ELF_APPENDED_DTB is not set - +CONFIG_MIPS_FP_SUPPORT=y - CONFIG_MIPS_L1_CACHE_SHIFT=5 - # CONFIG_MIPS_NO_APPENDED_DTB is not set - CONFIG_MIPS_RAW_APPENDED_DTB=y - @@ -217,6 +234,7 @@ CONFIG_RESET_ATH79=y - CONFIG_RESET_CONTROLLER=y - CONFIG_SERIAL_8250_NR_UARTS=1 - CONFIG_SERIAL_8250_RUNTIME_UARTS=1 - +# CONFIG_SERIAL_KGDB_NMI is not set - CONFIG_SERIAL_AR933X=y - CONFIG_SERIAL_AR933X_CONSOLE=y - CONFIG_SERIAL_AR933X_NR_UARTS=2 - @@ -248,3 +266,8 @@ CONFIG_TICK_CPU_ACCOUNTING=y - CONFIG_TINY_SRCU=y - CONFIG_USB_SUPPORT=y - CONFIG_USE_OF=y - +# CONFIG_VGACON_SOFT_SCROLLBACK is not set - +# CONFIG_VGA_CONSOLE is not set - +CONFIG_VT=y - +# CONFIG_VT_CONSOLE is not set - +# CONFIG_VT_HW_CONSOLE_BINDING is not set ++ The rest has then to be done with the gdb(-remote) instance on the host. ++ But the system must not be stopped too long because the external (GPIO) ++ will otherwise kill the system. + - Enabling python support for gdb - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++ Important here, is that OpenWrt 22.03 on some targets doesn't provide ++ the correctly mapped vmlinux in the source directory, So it is necessary to ++ run it like this: + - OpenWrt will build a gdb when ``CONFIG_GDB=y`` is set in .config. But it is - important to also enable the python support via ``CONFIG_GDB_PYTHON=y`` or - otherwise the Linux helper will not be able to correctly scan for modules. - This feature was only added **after** the OpenWrt 21.02 release. ++ $ cd "{LINUX_DIR}" ++ $ cp -r vmlinux-gdb.py vmlinux.debug-gdb.py ++ $ cp ../vmlinux.debug vmlinux.debug ++ $ "${GDB}" -iex "set auto-load safe-path `pwd`/scripts/gdb/" -iex "target remote localhost:5551" vmlinux.debug ++ (gdb) lx-symbols .. + - For older versions of OpenWrt (including 21.02.x), following script can also be - used: ++ Signed-off-by: Sven Eckelmann sven@narfation.org + - .. code-block:: diff - - diff --git a/toolchain/gdb/Makefile b/toolchain/gdb/Makefile - index 05e3c7de3c..0ab20cb2d5 100644 - --- a/toolchain/gdb/Makefile - +++ b/toolchain/gdb/Makefile - @@ -36,7 +36,7 @@ HOST_CONFIGURE_ARGS = \ - --without-included-gettext \ - --enable-threads \ - --with-expat \ - - --without-python \ - + --with-python \ - --disable-unit-tests \ - --disable-ubsan \ - --disable-binutils \ - @@ -49,9 +49,11 @@ define Host/Install - $(INSTALL_BIN) $(HOST_BUILD_DIR)/gdb/gdb $(TOOLCHAIN_DIR)/bin/$(TARGET_CROSS)gdb - ln -fs $(TARGET_CROSS)gdb $(TOOLCHAIN_DIR)/bin/$(GNU_TARGET_NAME)-gdb - strip $(TOOLCHAIN_DIR)/bin/$(TARGET_CROSS)gdb - + -$(MAKE) -C $(HOST_BUILD_DIR)/gdb/data-directory install - endef ++ diff --git a/config/Config-kernel.in b/config/Config-kernel.in ++ index 21a56e864098b8f652f06e319ce795a9456d5dcb..d0bc5e5d8b45cf6a0c63d86f5a2140980605373b 100644 ++ --- a/config/Config-kernel.in ++ +++ b/config/Config-kernel.in ++ @@ -11,6 +11,43 @@ config KERNEL_IPQ_MEM_PROFILE ++ This option select memory profile to be used,which defines ++ the reserved memory configuration used in device tree. + - define Host/Clean - + -$(MAKE) -C $(HOST_BUILD_DIR)/gdb/data-directory uninstall - rm -rf \ - $(HOST_BUILD_DIR) \ - $(TOOLCHAIN_DIR)/bin/$(TARGET_CROSS)gdb \ ++ +config KERNEL_VT ++ + bool ++ + ++ +config KERNEL_GDB_SCRIPTS ++ + bool ++ + ++ +config KERNEL_HW_CONSOLE ++ + bool ++ + ++ +config KERNEL_CONSOLE_POLL ++ + bool ++ + ++ +config KERNEL_MAGIC_SYSRQ ++ + bool ++ + ++ +config KERNEL_MAGIC_SYSRQ_SERIAL ++ + bool ++ + ++ +config KERNEL_KGDB_SERIAL_CONSOLE ++ + bool ++ + ++ +config KERNEL_KGDB_HONOUR_BLOCKLIST ++ + bool ++ + ++ +config KERNEL_KGDB ++ + select KERNEL_VT ++ + select KERNEL_GDB_SCRIPTS ++ + select KERNEL_HW_CONSOLE ++ + select KERNEL_CONSOLE_POLL ++ + select KERNEL_MAGIC_SYSRQ ++ + select KERNEL_MAGIC_SYSRQ_SERIAL ++ + select KERNEL_KGDB_SERIAL_CONSOLE ++ + select KERNEL_KGDB_HONOUR_BLOCKLIST ++ + select GDB_PYTHON ++ + bool "Enable kernel debugger over serial" ++ + ++ + ++ config KERNEL_BUILD_USER ++ string "Custom Kernel Build User Name" ++ default "builder" if BUILDBOT ++ diff --git a/include/kernel-build.mk b/include/kernel-build.mk ++ index 80da4455bc04fccd1c7834fe8b94c29399289bd2..4cbb8a861ed01a48d65a28f2d0b6e34837284cf2 100644 ++ --- a/include/kernel-build.mk ++ +++ b/include/kernel-build.mk ++ @@ -143,6 +143,7 @@ define BuildKernel ++ $(LINUX_DIR)/.image: $(STAMP_CONFIGURED) $(if $(CONFIG_STRIP_KERNEL_EXPORTS),$(KERNEL_BUILD_DIR)/symtab.h) FORCE ++ $(Kernel/CompileImage) ++ $(Kernel/CollectDebug) ++ + +[ -z "$(CONFIG_KERNEL_GDB_SCRIPTS)" ] || $(KERNEL_MAKE) scripts_gdb ++ touch $$@ ++ ++ mostlyclean: FORCE ++ diff --git a/target/linux/generic/config-5.10 b/target/linux/generic/config-5.10 ++ index 4a6efc88012580691b52493685992a2af7fa1c65..00238982863b98c2f340c7e6a76a19652c26d2c1 100644 ++ --- a/target/linux/generic/config-5.10 ++ +++ b/target/linux/generic/config-5.10 ++ @@ -7184,3 +7184,12 @@ CONFIG_ZONE_DMA=y ++ # CONFIG_ZRAM_MEMORY_TRACKING is not set ++ # CONFIG_ZSMALLOC is not set ++ # CONFIG_ZX_TDM is not set ++ + ++ +# KGDB specific "disabled" options ++ +# CONFIG_CONSOLE_TRANSLATIONS is not set ++ +# CONFIG_VT_CONSOLE is not set ++ +# CONFIG_VT_HW_CONSOLE_BINDING is not set ++ +# CONFIG_SERIAL_KGDB_NMI is not set ++ +# CONFIG_KGDB_TESTS is not set ++ +# CONFIG_KGDB_KDB is not set ++ +# CONFIG_KGDB_LOW_LEVEL_TRAP is not set + +Start debugging session +----------------------- + +Turning off kASLR +~~~~~~~~~~~~~~~~~ + +The kernel address space layout randomization complicates the resolving +of addresses of symbols. It is highly recommended to start the kernel - with the parameter "nokaslr". For example by adding it to CONFIG_CMDLINE ++with the parameter "nokaslr". For example by adding it to ``CONFIG_CMDLINE`` +or by adjusting the bootargs in the bootloader. It should be checked in +/proc/cmdline whether it was really booted with this parameter. + +Configure KGDB serial +~~~~~~~~~~~~~~~~~~~~~ + +The kgdb needs a serial device to work. This has to be set in the module +parameter. We assume now that the serial console on our device is ttyS0 +with baudrate 115200: + +.. code-block:: sh + - echo ttyS0,115200 > /sys/module/kgdboc/parameters/kgdboc ++ echo ttyS0,115200 > /sys/module/kgdboc/parameters/kgdboc + +Switch to kgdb +~~~~~~~~~~~~~~ + +The gdb frontend cannot directly talk to the kernel over serial and +create breakpoints. The sysrq mechanism has to be used to switch from +Linux to kgdb before gdb can be used. Under OpenWrt, this can be done +using + +.. code-block:: sh + - echo g > /proc/sysrq-trigger ++ echo g > /proc/sysrq-trigger + +Connecting gdb +~~~~~~~~~~~~~~ + +I would use following folder in my x86-64 build environment but they +will be different for other architectures or OpenWrt versions: + - * ``LINUX_DIR=${OPENWRT_DIR}/build_dir/target-x86_64_musl/linux-x86_64/linux-5.4.143/`` - * ``GDB=${OPENWRT_DIR}/staging_dir/toolchain-x86_64_gcc-8.4.0_musl/bin/x86_64-openwrt-linux-gdb`` - * ``BATADV_DIR=${OPENWRT_DIR}/build_dir/target-x86_64_musl/linux-x86_64/batman-adv-2021.1/`` ++- LINUX_DIR=${OPENWRT_DIR}/build_dir/target-x86_64_musl/linux-x86_64/linux-5.10.146/ ++- GDB=${OPENWRT_DIR}/staging_dir/staging_dir/toolchain-x86_64_gcc-11.2.0_musl/bin/x86_64-openwrt-linux-gdb ++- BATADV_DIR=${OPENWRT_DIR}/build_dir/target-x86_64_musl/linux-x86_64/batman-adv-2022.0/ + +When kgdb is activated using sysrq, we can configure gdb. It has to +connect via a serial adapter to the target device. We must change to the +LINUX_DIR first and can then start our target specific GDB with our +uncompressed kernel image before we will connect to the remote device. + +.. code-block:: sh + + cd "${LINUX_DIR}" ++ cp ../vmlinux.debug vmlinux + "${GDB}" -iex "set auto-load safe-path scripts/gdb/" -iex "set serial baud 115200" -iex "target remote /dev/ttyUSB0" ./vmlinux + +In this example, we are using an USB TTL converter (/dev/ttyUSB0). It +has to be configured in gdb + +:: + + lx-symbols .. + + continue + +You should make sure that it doesn't load any \ **.ko files from +ipkg-**\ directories. These files are stripped and doesn't contain the +necessary symbol information. When necessary, just delete these folders +or specify the folders with the unstripped kernel modules: + +:: + - lx-symbols ../batman-adv-2021.1/.pkgdir/ ../backports-5.10.42-1/.pkgdir/ ../button-hotplug/.pkgdir/ ++ lx-symbols ../batman-adv-2022.0/.pkgdir/ ../backports-5.15.58-1/.pkgdir/ ../button-hotplug/.pkgdir/ + +The rest of the process works similar to debugging using gdbserver. Just +set some additional breakpoints and let the kernel run again. kgdb will +then inform gdb whenever a breakpoints was hit. Just keep in mind that +it is not possible to interrupt the kernel from gdb (without a Oops or +an already existing breakpoint) - use the sysrq mechanism again from +Linux to switch back to kgdb. + - Some other ideas are documented in - :doc:`GDB_Linux_snippets`. ++Some other ideas are documented in :doc:`GDB_Linux_snippets`. + +The kernel hacking debian image page should also be checked to +:ref:`increase the chance of getting debugable modules <devtools-hacking-debian-image-building-the-batman-adv-module>` which didn't had all +information optimized away. The relevant flags could be set directly in +the routing feed like this: + +.. code-block:: diff + + diff --git a/batman-adv/Makefile b/batman-adv/Makefile + index 967965e..0abd42f 100644 + --- a/batman-adv/Makefile + +++ b/batman-adv/Makefile + @@ -17,6 +17,9 @@ PKG_LICENSE_FILES:=LICENSES/preferred/GPL-2.0 LICENSES/preferred/MIT + + STAMP_CONFIGURED_DEPENDS := $(STAGING_DIR)/usr/include/mac80211-backport/backport/autoconf.h + + +RSTRIP:=: + +STRIP:=: + + + include $(INCLUDE_DIR)/kernel.mk + include $(INCLUDE_DIR)/package.mk + + @@ -77,7 +80,7 @@ define Build/Compile - $(KERNEL_MAKE_FLAGS) \ - M="$(PKG_BUILD_DIR)/net/batman-adv" \ - $(PKG_EXTRA_KCONFIG) \ - - EXTRA_CFLAGS="$(PKG_EXTRA_CFLAGS)" \ - + EXTRA_CFLAGS="$(PKG_EXTRA_CFLAGS) -fno-inline -Og -fno-optimize-sibling-calls" \ - NOSTDINC_FLAGS="$(NOSTDINC_FLAGS)" \ - modules ++ $(KERNEL_MAKE_FLAGS) \ ++ M="$(PKG_BUILD_DIR)/net/batman-adv" \ ++ $(PKG_EXTRA_KCONFIG) \ ++ - EXTRA_CFLAGS="$(PKG_EXTRA_CFLAGS)" \ ++ + EXTRA_CFLAGS="$(PKG_EXTRA_CFLAGS) -fno-inline -Og -fno-optimize-sibling-calls" \ ++ NOSTDINC_FLAGS="$(NOSTDINC_FLAGS)" \ ++ modules + endef + +Agent-Proxy +----------- + +Instead of switching all the time between gdb and the terminal emulator - (via UART/TTL), it can be rather helpful to use a splitter which can multiplex - the kgdb and the normal terminal. So instead of using screen/minicom/... + gdb - against the tty device, the different sessions are just started against a TCP - port. ++(via UART/TTL), it can be rather helpful to use a splitter which can ++multiplex the kgdb and the normal terminal. So instead of using ++screen/minicom/... + gdb against the tty device, the different sessions ++are just started against a TCP port. + +Installation +~~~~~~~~~~~~ + - .. code-block:: shell ++.. code-block:: sh + + $ git clone https://git.kernel.org/pub/scm/utils/kernel/kgdb/agent-proxy.git/ + $ make -C agent-proxy + +Starting up session +~~~~~~~~~~~~~~~~~~~ + - .. code-block:: shell ++.. code-block:: sh + + $ ./agent-proxy/agent-proxy '127.0.0.1:5550^127.0.0.1:5551' 0 /dev/ttyUSB0,115200 + +To connect to the terminal session, a simple telnet or telnet-like tool +is enough: + - .. code-block:: shell ++.. code-block:: sh + + $ screen //telnet localhost 5550 + - The setup of the kgdboc must happen exactly as described before. Including the - switch to the debugging mode via sysrq. ++The setup of the kgdboc must happen exactly as described before. ++Including the switch to the debugging mode via sysrq. + +The gdb has to be attached like to a remote gdb session + - .. code-block:: shell ++.. code-block:: sh + + $ cd "${LINUX_DIR}" + $ "${GDB}" -iex "set auto-load safe-path scripts/gdb/" -iex "target remote localhost:5551" ./vmlinux + +Enable KGDB on panic +-------------------- + - Usually, a debugger catches problems like segfaults and allows a user to debug - the problem further. On modern setups with kgdb, this is not the case becaus - the system will automatically reboot after n-seconds. ++Usually, a debugger catches problems like segfaults and allows a user to ++debug the problem further. On modern setups with kgdb, this is not the ++case because the system will automatically reboot after n-seconds. + - This can be avoided by changing the sysctl config ``kernel.panic`` to 0. Either - in ``/etc/sysctl.d/`` or by manually issuing ++This can be avoided by changing the sysctl config ``kernel.panic`` to 0. ++Either in ``/etc/sysctl.d/`` or by manually issuing + - .. code-block:: shell ++.. code-block:: sh + + sysctl -w kernel.panic=0 + - If a kgdb(oc) is attached then it should automatically receive a message when - the Oops was noticed and can then be debugged further. ++If a kgdb(oc) is attached then it should automatically receive a message ++when the Oops was noticed and can then be debugged further. diff --cc open-mesh/Download.rst index 0df41045,00000000..96f8a37c mode 100644,000000..100644 --- a/open-mesh/Download.rst +++ b/open-mesh/Download.rst @@@ -1,270 -1,0 +1,272 @@@ +.. SPDX-License-Identifier: GPL-2.0 + +Download B.A.T.M.A.N. +===================== + +We are currently working on different branches. To get the details about +the differences of these branches, see our :doc:`Branches Explained page <BranchesExplained>`. + +Please use the maint branch for your public infrastructure unless you +know exactly what you are doing and are prepared for the big unknown. + +.. _open-mesh-download-download-released-source-code: + +Download Released Source Code +----------------------------- + +- The latest version of batman-adv is - `batman-adv-2022.2.tar.gz https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.2.tar.gz`__ - `md5 https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.2.tar.gz.md5`__ - `sha1 https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.2.tar.gz.sha1`__ - `asc https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.2.tar.gz.asc`__ ++ `batman-adv-2022.3.tar.gz https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.3.tar.gz`__ ++ `md5 https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.3.tar.gz.md5`__ ++ `sha1 https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.3.tar.gz.sha1`__ ++ `asc https://downloads.open-mesh.org/batman/stable/sources/batman-adv/batman-adv-2022.3.tar.gz.asc`__ +- The latest version of batctl (management and control tool for + batman-adv) is - `batctl-2022.2.tar.gz https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.2.tar.gz`__ - `md5 https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.2.tar.gz.md5`__ - `sha1 https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.2.tar.gz.sha1`__ - `asc https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.2.tar.gz.asc`__ ++ `batctl-2022.3.tar.gz https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.3.tar.gz`__ ++ `md5 https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.3.tar.gz.md5`__ ++ `sha1 https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.3.tar.gz.sha1`__ ++ `asc https://downloads.open-mesh.org/batman/stable/sources/batctl/batctl-2022.3.tar.gz.asc`__ +- The latest version of alfred (Almighty Lightweight Fact Remote + Exchange Daemon) is - `alfred-2022.2.tar.gz https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.2.tar.gz`__ - `md5 https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.2.tar.gz.md5`__ - `sha1 https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.2.tar.gz.sha1`__ - `asc https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.2.tar.gz.asc`__ ++ `alfred-2022.3.tar.gz https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.3.tar.gz`__ ++ `md5 https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.3.tar.gz.md5`__ ++ `sha1 https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.3.tar.gz.sha1`__ ++ `asc https://downloads.open-mesh.org/batman/stable/sources/alfred/alfred-2022.3.tar.gz.asc`__ + +- The latest stable version of batmand + (:ref:`unmaintained <open-mesh-BranchesExplained-batmand>`) is + `batman-0.3.2.tar.gz https://downloads.open-mesh.org/batman/releases/batman-0.3.2/batman-0.3.2.tar.gz`__ + `md5 https://downloads.open-mesh.org/batman/releases/batman-0.3.2/batman-0.3.2.tar.gz.md5`__ + `sha1 https://downloads.open-mesh.org/batman/releases/batman-0.3.2/batman-0.3.2.tar.gz.sha1`__ + `asc https://downloads.open-mesh.org/batman/releases/batman-0.3.2/batman-0.3.2.tar.gz.asc`__ +- The latest version of the vis server for the batmand (package not + needed for batman-adv) is + `vis-0.3.2.tar.gz https://downloads.open-mesh.org/batman/releases/batman-0.3.2/vis-0.3.2.tar.gz`__ + `md5 https://downloads.open-mesh.org/batman/releases/batman-0.3.2/vis-0.3.2.tar.gz.md5`__ + `sha1 https://downloads.open-mesh.org/batman/releases/batman-0.3.2/vis-0.3.2.tar.gz.sha1`__ + `asc https://downloads.open-mesh.org/batman/releases/batman-0.3.2/vis-0.3.2.tar.gz.asc`__ + +If you are wondering whether batman-adv or batmand might suit your setup +better, have a look at :doc:`this page </batman-adv/Wiki>`. Please note that +the development is focusing on batman-adv at the moment. + +To download previous release tarballs, simply check out our `download +section https://downloads.open-mesh.org/batman/releases/`__. + +If you find any bugs, please :doc:`let us know <Contribute>`! + +Git Repository Access +--------------------- + +Since we started integrating the batman-adv kernel module into the +mainline Linux tree, we maintain a git repository which contains the +batman-adv maintenance branches. More information can be found +:doc:`on our git page <UsingBatmanGit>`. +On overview about all the git repositories can be found on our `git +frontend https://git.open-mesh.org`__. We also host individual +repositories for development related to batman or meshing in general. +Feel free to contact us if you are interested in getting a repository +too. + +batman-adv in the Linux tree +---------------------------- + +Since linux 2.6.33 batman-adv is part of the official linux tree. You +can build batman-adv along with your linux binary by simply selecting +batman-adv in the Linux drivers section. If you want to have access to +the latest features on a non-bleeding edge kernel, you can clone our +git repository which still are backward compatible to all +stable/longterm kernels. + +It follows an overview of linux versions and the batman-adv version they +contain, so that you can easily pick the compatible batctl packages: + +- linux 2.6.33 => batman-adv 0.2.0 (get batctl 0.2.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 2.6.34 => batman-adv 0.2.1 (get batctl 0.2.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 2.6.35 => batman-adv 2010.0.x (get batctl 2010.0.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 2.6.36 => batman-adv 2010.1.x (get batctl 2010.1.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 2.6.37 => batman-adv 2010.2.x (get batctl 2010.2.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 2.6.38 => batman-adv 2011.0.x (get batctl 2011.0.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 2.6.39 => batman-adv 2011.1.x (get batctl 2011.1.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.0 => batman-adv 2011.2.x (get batctl 2011.2.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.1 => batman-adv 2011.3.x (get batctl 2011.3.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.2 => batman-adv 2011.4.x (get batctl 2011.4.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.3 => batman-adv 2012.0.x (get batctl 2012.0.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.4 => batman-adv 2012.1.x (get batctl 2012.1.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.5 => batman-adv 2012.2.x (get batctl 2012.2.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.6 => batman-adv 2012.3.x (get batctl 2012.3.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.7 => batman-adv 2012.4.x (get batctl 2012.4.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.8 => batman-adv 2013.0.x (get batctl 2013.0.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.9 => batman-adv 2013.1.x (get batctl 2013.1.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.10 => batman-adv 2013.2.x (get batctl 2013.2.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.11 => batman-adv 2013.3.x (get batctl 2013.3.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.12 => batman-adv 2013.4.x (get batctl 2013.4.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.13 => batman-adv 2014.0.x (get batctl 2014.0.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ + NOTE: in-kernel version number is 2013.5.0 +- linux 3.14 => batman-adv 2014.1.x (get batctl 2014.1.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.15 => batman-adv 2014.2.x (get batctl 2014.2.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.16 => batman-adv 2014.3.x (get batctl 2014.3.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 3.17-3.19 => batman-adv 2014.4.x (get batctl 2014.4.x from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.0-4.1 => batman-adv 2015.0 (get batctl 2015.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/`__ +- linux 4.2-4.3 => batman-adv 2015.1 (get batctl 2015.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.4 => batman-adv 2015.2 (get batctl 2015.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.5 => batman-adv 2016.0 (get batctl 2016.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.6 => batman-adv 2016.1 (get batctl 2016.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.7 => batman-adv 2016.2 (get batctl 2016.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.8 => batman-adv 2016.3 (get batctl 2016.3 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.9 => batman-adv 2016.4 (get batctl 2016.4 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.10 => batman-adv 2016.5 (get batctl 2016.5 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.11 => batman-adv 2017.0.1 (get batctl 2017.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.12 => batman-adv 2017.1 (get batctl 2017.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.13 => batman-adv 2017.2 (get batctl 2017.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.14 => batman-adv 2017.3 (get batctl 2017.3 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.15 => batman-adv 2017.4 (get batctl 2017.4 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.16 => batman-adv 2018.0 (get batctl 2018.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.17 => batman-adv 2018.1 (get batctl 2018.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.18 => batman-adv 2018.2 (get batctl 2018.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.19 => batman-adv 2018.3 (get batctl 2018.3 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 4.20 => batman-adv 2018.4 (get batctl 2018.4 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.0 => batman-adv 2019.0 (get batctl 2019.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.1 => batman-adv 2019.1 (get batctl 2019.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.2 => batman-adv 2019.2 (get batctl 2019.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.3 => batman-adv 2019.3 (get batctl 2019.3 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.4 => batman-adv 2019.4 (get batctl 2019.4 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.5 => batman-adv 2019.5 (get batctl 2019.5 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.6 => batman-adv 2020.0 (get batctl 2020.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.7 => batman-adv 2020.1 (get batctl 2020.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.8 => batman-adv 2020.2 (get batctl 2020.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.9 => batman-adv 2020.3 (get batctl 2020.3 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.10 => batman-adv 2020.4 (get batctl 2020.4 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.11 => batman-adv 2021.0 (get batctl 2021.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.13 => batman-adv 2021.1 (get batctl 2021.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.14 => batman-adv 2021.2 (get batctl 2021.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.15 => batman-adv 2021.3 (get batctl 2021.3 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.16 => batman-adv 2021.4 (get batctl 2021.4 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.17 => batman-adv 2022.0 (get batctl 2022.0 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.18 => batman-adv 2022.1 (get batctl 2022.1 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ +- linux 5.19 => batman-adv 2022.2 (get batctl 2022.2 from + `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ ++- linux 6.1 => batman-adv 2022.3 (get batctl 2022.3 from ++ `here https://downloads.open-mesh.org/batman/stable/sources/batctl/)`__ + +Arch Linux +---------- + +Batman-adv and Batctl are avaible in the +`AUR https://wiki.archlinux.org/index.php/AUR`__ as PKGBUILD: + +- `batctl https://aur.archlinux.org/packages/batctl/`__ - Latest + Batctl +- `batman-adv https://aur.archlinux.org/packages/batman-adv/`__ - + Latest Batman-adv +- `batman-adv-v14 https://aur.archlinux.org/packages/batman-adv-v14/`__ + - Last Batman-adv with compability-version 14 (2013.4) +- `batctl-v14 https://aur.archlinux.org/packages/batctl-v14/`__ - + Last Batctl with compability-version 14 (2013.4) + +Debian +------ + +Use apt-get (or any other dpkg frontend of choice) to install +B.A.T.M.A.N. onto your debian machine. Following packages are available: + +- `alfred https://packages.debian.org/sid/alfred`__ +- `batmand https://packages.debian.org/sid/batmand`__ +- `batctl https://packages.debian.org/sid/batctl`__ +- `linux https://packages.debian.org/source/unstable/linux`__ - + batman-advanced kernel module as `part of the + official https://bugs.debian.org/622361`__ kernel packages + +Similar packages are also available through `Ubuntu +universe https://help.ubuntu.com/community/Repositories/Ubuntu`__ . + +Gentoo +------ + +Use emerge to build B.A.T.M.A.N. on your gentoo machine. Following +ebuilds are available: + +- `net-misc/batctl https://packages.gentoo.org/packages/net-misc/batctl`__ +- `net-misc/batman-adv https://packages.gentoo.org/packages/net-misc/batman-adv`__ + +openSUSE +-------- + +- `network:utilities / + batctl https://build.opensuse.org/package/show?package=batctl&project=network%3Autilities`__ +- the batman-adv module is available as module in the official kernel + packages + +Building OpenWRT packages +------------------------- + +B.A.T.M.A.N. is also included in OpenWRT as a package. Download the +extra package feed, link the batman folder into your main OpenWRT svn +directory and use "make menuconfig" to select the B.A.T.M.A.N. flavor +you intend to use. This enables you to integrate B.A.T.M.A.N. seamlessly +into your builds (see :doc:`this page </batman-adv/Building-with-openwrt>` for +a detailed explanation). + +More information about how to build the OpenWRT toolchain is available +`here https://wiki.openwrt.org/doc/howto/build`__.