products/adsp: Add early kernel debug info by Brandon-Hurst · Pull Request #426 · analogdevicesinc/documentation

Brandon-Hurst · 2026-04-14T22:11:09Z

Description

This PR adds a document for ADSP Linux showing how to debug the early kernel boot before even the early console can be up and running. This will assist developers who are working on crashing systems.

Testing performed includes running the procedure described in the document to step debug the early kernel booting process from the U-Boot bootloader environment.

Type

Documentation
Bug fix
New feature
Continuous integration

Checklist

I have performed a self-review of changes
I have followed the guidelines:
I have used the appropriate roles and directives:
- https://analogdevicesinc.github.io/doctools/docs_guidelines/roles.html
- https://analogdevicesinc.github.io/doctools/docs_guidelines/directives.html
I ensured that binary data was committed to git lfs:
- https://analogdevicesinc.github.io/documentation/contributing/creating_new_pages.html#adding-images-and-other-binary-files
I have built the pages I edited or created, using either make html or adoc serve:
- https://analogdevicesinc.github.io/doctools/cli.html#serve
I have signed-off my commits and believe my contribution improves the repository.

Brandon-Hurst · 2026-04-14T22:20:06Z

@pamolloy You may be interested / have comments in this

pamolloy · 2026-04-20T11:17:07Z

+         file://feature/cfg/tracepoints.cfg \
+         file://feature/cfg/debug-symbols.cfg
+   "
+   # ...


Perhaps include this in fragment in the Yocto meta layer? In Buildroot we already generate a debug image

Are you saying you'd like me to make this modification here? Do you want this as the default behavior?
https://github.com/analogdevicesinc/lnxdsp-adi-meta

pamolloy · 2026-04-20T11:24:41Z

+     -ex "target extended-remote localhost:3333" \
+     -ex "set print pretty on" \
+     -ex "set pagination off" \
+     -ex "add-symbol-file $VMLINUX $LOAD_ADDR"


CC @ozan956 I guess we can add a linux.gdb script?

See https://github.com/analogdevicesinc/documentation/blob/main/docs/products/adsp/u-boot.gdb

We can create something like:

set print pretty on target extended-remote localhost:3333 add-symbol-file ${VMLINUX} ${LOAD_ADDR}

and I believe LOAD_ADDR is static.

We can also suggest them to copy vmlinux-dbg at location where we run gdb, in here 1027cd5#diff-1d796e9c7f37c59e3cd76a83b6b15b00852abcb170a4143304d76a6bec3be71cR109-R111

If we do that we can also create a file as:

set print pretty on target extended-remote localhost:3333 add-symbol-file vmlinux-dbg 0xC3000000

pamolloy · 2026-04-20T11:29:01Z

Thanks @Brandon-Hurst! Definitely some really helpful snippets.

Generally it would be good to remove the Yocto specifics and generic documentation. Assume someone already has a working Kernel build. Try to keep the article as concise as possible. It will help us keep the documentation maintainable in the future.

Add a document for ADSP Linux showing how to debug the early kernel boot before even the early console can be up and running. This will assist developers who are working on crashing systems. Testing performed is exactly as described in the document. Signed-off-by: Brandon Hurst <brandon.hurst@analog.com>

Brandon-Hurst · 2026-04-22T01:46:15Z

Thanks @Brandon-Hurst! Definitely some really helpful snippets.

Generally it would be good to remove the Yocto specifics and generic documentation. Assume someone already has a working Kernel build. Try to keep the article as concise as possible. It will help us keep the documentation maintainable in the future.

No problem! It was an interesting task.

My thought in doing this was to follow the current Yocto system. In Yocto, these artifacts are not easy to find, so calling out the specific paths for the Yocto build system could be helpful (otherwise finding the vmlinux file after building linux-adi is tough, for example). My experience is also that it's not straightforward to migrate most tasks between Buildroot and Yocto, so I think having a generic guide that serves both would be difficult.

Do you want it based on Buildroot, and just using menuconfig? I could also make this a separate guide for Yocto and a different one for Buildroot, but I think that would be harder to maintain.

ozan956 · 2026-04-24T12:51:19Z

+get more information about these commands. Other useful resources are the GDB
+documentation and `ADI's GDB Command Reference <https://developer.analog.com/docs/codefusion-studio/latest/tutorials/gdb-tutorial/gdb-commands/>`_.
+
+The below example sets a breakpount while the target is in U-Boot, which gets


typo "breakpount"

ozan956 · 2026-04-24T13:02:46Z

+     -ex "target extended-remote localhost:3333" \
+     -ex "set print pretty on" \
+     -ex "set pagination off" \
+     -ex "add-symbol-file $VMLINUX $LOAD_ADDR"


We can create something like:

set print pretty on target extended-remote localhost:3333 add-symbol-file ${VMLINUX} ${LOAD_ADDR}

and I believe LOAD_ADDR is static.

We can also suggest them to copy vmlinux-dbg at location where we run gdb, in here 1027cd5#diff-1d796e9c7f37c59e3cd76a83b6b15b00852abcb170a4143304d76a6bec3be71cR109-R111

If we do that we can also create a file as:

set print pretty on target extended-remote localhost:3333 add-symbol-file vmlinux-dbg 0xC3000000

ozan956 · 2026-04-24T13:08:12Z

+   #!/bin/bash
+   # GDB helper script for SC589-MINI kernel debugging
+
+   GDB="/opt/adi-distro-glibc/5.0.1/sysroots/x86_64-adi_glibc_sdk-linux/usr/bin/arm-adi_glibc-linux-gnueabi/arm-adi_glibc-linux-gnueabi-gdb"


Do we specifically need that gdb instance?

It is good practice to make sure that the GDB build is one that matches the toolchain, i.e. the populated SDK from Yocto in this case. It's unlikely that this specific one is need though since the target is ARM in this case. It's possible that using gdb-multiarch or arm-linux-gnueabi-gdb would work, but I still prefer the solution using the toolchain populated by our Yocto tools, primarily because it's also required for OpenOCD and I'm not sure if there are specific things about that toolchain build that if not present could break the process in this document.

There is no hard requirement for Yocto toolchain for gdb. OpenOCD have ADSP specific changes, so that's need to be from toolchain or self compiled. Im only using gdb-multiarch for debugging as usually it have latest python version for plugins and more features.

Also there is hardcoded version of Yocto release, can it be sourced like
. /opt/adi-distro-glibc/5.0.1/environment-setup-cortexa55-adi_glibc-linux
and then no need to specify version each time new release comes

ozan956 · 2026-04-24T13:18:45Z

+To check whether a given ``vmlinux`` file contains debug symbols, use the
+``file`` or ``readelf`` utilities. The following example shows the ``file`` output
+for a modified :git-lnxdsp-adi-meta:` v5.0.1 Yocto release <releases/tag/5.0.1-rel+>`
+with a :git-linux:`6.12 Linux release <commits/adsp-6.12.0-y+>`, but the


We can point to release also:

:git-linux:`Release 1 <releases/tag/adsp-6.12.0-1+>` :git-linux:`Release 2 <releases/tag/6.12.0-2+>` :git-linux:`Release 3 <releases/tag/6.12.0-3+>`

Brandon-Hurst force-pushed the adsp/add-debug-guide branch 3 times, most recently from 0d243ed to fdd422a Compare April 14, 2026 22:28

analogdevicesinc deleted a comment from github-actions Bot Apr 15, 2026

pamolloy added this to ADSP Apr 20, 2026

pamolloy requested review from a team, gastmaier, ozan956 and pamolloy April 20, 2026 10:45

pamolloy requested changes Apr 20, 2026

View reviewed changes

pamolloy moved this to In Development in ADSP Apr 20, 2026

qasim-ijaz reviewed Apr 20, 2026

View reviewed changes

Brandon-Hurst force-pushed the adsp/add-debug-guide branch from fdd422a to 1027cd5 Compare April 22, 2026 01:29

ozan956 reviewed Apr 24, 2026

View reviewed changes

Conversation

Brandon-Hurst commented Apr 14, 2026

Description

Type

Checklist

Uh oh!

Brandon-Hurst commented Apr 14, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pamolloy commented Apr 20, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Brandon-Hurst commented Apr 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants