Integrate debug tools into aiebu-dump

[AdvaitNaik]

Problem solved by the commit

add frequently used standalone python debug tools to aiebu-dump utility

• elf map reader - parse the map and print dynamic tracing probe lines
• opcode information - given pc and page index, resolve the matching map entry and print opcode metadata

Bug / issue (if any) fixed, which PR introduced the bug, how it was discovered

NA

How problem was solved, alternative solutions (if any) and why they were rejected

https://amd.atlassian.net/wiki/spaces/AIE/pages/1583345872/Integrate+.dump+debug+map+tools+into+aiebu-dump

.\WBuild\Debug\xilinx\aiebu\aiebu-dump.exe -H
aiebu dumping utility (aiebu-dump) for aie binaries
Usage:
  aiebu-dump [OPTION...] positional parameters

  -a, --archive-headers   Display archive header information
  -f, --file-headers      Display the contents of the overall file header
  -p, --private-headers   Display opcode frequency in the control code
                          binary
  -x, --all-headers       Display contents of all elf headers
  -d, --disassemble       Display assembler contents of ctrltext sections
                          if elf file is provided or display control packet
                          in assembled format if control packet binary file
                          is provided
  -H, --help              show help message and exit
  -m, --architecture arg  Specify the target architecture as MACHINE
                          (aie2ps/aie4/aie2asm/aie2txn/aie2dpu). Required
                          for binary files to select correct ISA. (default:
                          unspecified)
  -D, --disassemble-all   Display assembler contents of all sections
  -t, --syms              Display contents of the symbols table(s)
  -r, --reloc             Display relocation entries in the file
  -P, --private arg       Display object format specific contents
                          arg:
                          trace-probe   Display probe information
                          opcode-info   Display opcode information
                           (default: unspecified)
      --pc arg            Program counter for opcode-info (default:
                          unspecified)
      --page-index arg    Page index for opcode-info (default: unspecified)
      --uc-index arg      uC (column) index for opcode-info (default:
                          unspecified)
  -v, --version           show version and exit

Risks (if any) associated the changes in the commit

NA

What has been tested and how, request additional testing if necessary

.\WBuild\Debug\xilinx\aiebu\aiebu-dump.exe --private trace-probe .\control.elf
jprobe:default:uc0:line5 ( on START_JOB 0 )
jprobe:default:uc0:line6 ( on LOAD_PDI 0, @pdi )
jprobe:default:uc0:line7 ( on END_JOB )
jprobe:default:uc0:line9 ( on START_JOB 1 )
jprobe:default:uc0:line10 ( on WRITE_32            0x200000, 0xabcdabcd )
jprobe:default:uc0:line11 ( on uC_DMA_WRITE_DES    $r0, @uc_dma_bd0 )
jprobe:default:uc0:line12 ( on WAIT_uC_DMA         $r0 )
jprobe:default:uc0:line13 ( on LOCAL_BARRIER       $lb0, 2 )
jprobe:default:uc0:line14 ( on END_JOB )
jprobe:default:uc0:line16 ( on START_JOB 2 )
jprobe:default:uc0:line17 ( on LOCAL_BARRIER       $lb0, 2 )
jprobe:default:uc0:line19 ( on WRITE_32            0x0109E6C, 0x80000000 )
jprobe:default:uc0:line21 ( on WRITE_32            0x2109E0C, 0x80000000 )
...

.\WBuild\Debug\xilinx\aiebu\aiebu-dump.exe --private opcode-info --pc 0x48 --page-index 0 .\control.elf
ELF File:       .\control.elf
PC:             0x48
Opcode Information:
Opcode:         LOCAL_BARRIER       $lb0, 2
Opcode Size:    0x4
uC Index:       0x0
Page Index:     0x0
Page Offset:    0x48
Line:           13
File:           default

.\WBuild\Debug\xilinx\aiebu\aiebu-dump.exe --private opcode-info --pc 0x01 --page-index 0x1 .\control.elf
ELF File:       .\control.elf
PC:             0x1
Opcode Information:
Not found!

Documentation impact (if any)

updated - AIEBU_USER_MANUAL

[github-actions]

clang-tidy made some suggestions

[Copilot]

Pull request overview

This PR integrates standalone debug tooling into the aiebu-dump utility by adding new “private” modes that extract .dump JSON debug data from supported ELFs and print trace probe listings or opcode metadata.

Changes:

• Add --private trace-probe and --private opcode-info modes to aiebu-dump, including new CLI args (--pc, --page-index, --uc-index).
• Introduce a new C++ debug_tools helper plus implementations for trace probe listing and opcode info lookup.
• Wire new tool sources into the C++ build and document the new CLI options in the user manual.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
src/cpp/utils/dump/dump.cpp	Adds --private CLI plumbing and dispatch into the new debug tooling.
src/cpp/tools/debug_tools.h	Declares the debug_tools helper used to extract cached .dump JSON.
src/cpp/tools/debug_tools.cpp	Implements .dump extraction/caching using transform_manager.
src/cpp/tools/trace_probe.cpp	Implements trace probe listing output from .dump JSON.
src/cpp/tools/opcode_information.cpp	Implements opcode lookup/output by PC + page (+ optional uC).
src/cpp/CMakeLists.txt	Adds the new tool sources to the build.
AIEBU_USER_MANUAL.rst	Documents new --private modes and arguments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

clang-tidy review says "All clean, LGTM! 👍"

[github-actions]

clang-tidy review says "All clean, LGTM! 👍"

[github-actions]

clang-tidy review says "All clean, LGTM! 👍"

[github-actions]

clang-tidy review says "All clean, LGTM! 👍"