RPMsg Dump and Ping Documentation

[CV-Bowen]

Summary

This PR adds comprehensive documentation for RPMsg diagnostic tools and introduces priority support for RPMsg endpoints.

Motivation

1. Documentation Gap: The RPMsg subsystem lacked documentation for its diagnostic tools (rpmsg ping and rpmsg dump), making it difficult for developers to troubleshoot inter-processor communication issues.

2. Debugging Visibility: The virtqueue dump logs were using METAL_LOG_DEBUG level, which could be filtered out in production builds, making debugging difficult when issues occur.

3. Priority Support: Different RPMsg endpoints may have different importance levels. Adding priority support allows for future scheduling optimizations and better resource management.

Changes

1. Documentation: RPMsg Ping (rpmsg_ping.rst)

Added comprehensive documentation for the RPMsg Ping diagnostic tool:

• Command syntax and parameters explanation
• Usage examples with sample output
• Architecture workflow diagram showing the complete ping process
• Best practices for latency and throughput testing

2. Documentation: RPMsg Dump (rpmsg_dump.rst)

Added detailed documentation for the RPMsg Dump command:

• Output format description (CPU info, endpoint list, virtqueue dump, buffer states)
• Field-by-field explanation of dump output
• Common debugging use cases:
  • TX buffer timeout issues
  • Communication failures
  • Buffer leak detection

3. OpenAMP Patch: Virtqueue Dump Log Level

Changed virtqueue_dump() log level from METAL_LOG_DEBUG to METAL_LOG_EMERGENCY to ensure dump information is always visible when debugging issues.

4. OpenAMP Patch: RPMsg Endpoint Priority

Added priority field to struct rpmsg_endpoint:

• Priority constants: RPMSG_PRIO_MIN (0), RPMSG_PRIO_DEFAULT (127), RPMSG_PRIO_MAX (255)
• RPMSG_PRIO_RT alias for real-time priority
• Auto-initialization to default priority in rpmsg_register_endpoint()

Impact

• Stability: No impact - documentation only changes and additive API changes
• Compatibility: Fully backward compatible - priority field defaults to 127 if not explicitly set
• Documentation: Significantly improves developer experience for RPMsg debugging
• Breaking Changes: None

Testing

Build Verification

# Configure and build for QEMU ARMv8-A
cmake -B cmake_out/v8a_server -DBOARD_CONFIG=qemu-armv8a:v8a_server -GNinja
cmake --build cmake_out/v8a_server

cmake -B cmake_out/v8a_proxy -DBOARD_CONFIG=qemu-armv8a:v8a_proxy -GNinja
cmake --build cmake_out/v8a_proxy

Documentation Build

cd Documentation
make html
# Verify new .rst files render correctly

Runtime Testing (QEMU Dual-Core)

Test Environment:

• Host: Linux x86_64
• Target: QEMU ARMv8-A (dual-core simulation)
• Configuration: qemu-armv8a:v8a_server + qemu-armv8a:v8a_proxy

Log

server> rpmsg ping all 1 1 1 1
[    0.000000] [ 7] [ EMERG] [server] ping times: 1
[    0.000000] [ 7] [ EMERG] [server] buffer_len: 1520, send_len: 17
[    0.000000] [ 7] [ EMERG] [server] avg: 0 s, 16954704 ns
[    0.000000] [ 7] [ EMERG] [server] min: 0 s, 16954704 ns
[    0.000000] [ 7] [ EMERG] [server] max: 0 s, 16954704 ns
[    0.000000] [ 7] [ EMERG] [server] rate: 0.008021 Mbits/sec
[    0.000000] [ 7] [ EMERG] [server] ping times: 1
[    0.000000] [ 7] [ EMERG] [server] buffer_len: 2024, send_len: 17
[    0.000000] [ 7] [ EMERG] [server] avg: 0 s, 16483360 ns
[    0.000000] [ 7] [ EMERG] [server] min: 0 s, 16483360 ns
[    0.000000] [ 7] [ EMERG] [server] max: 0 s, 16483360 ns
[    0.000000] [ 7] [ EMERG] [server] rate: 0.008250 Mbits/sec
server> 
server> 
server> rpmsg dump all
[    0.000000] [ 7] [ EMERG] [server] Local: server Remote: proxy Headrx 8
[    0.000000] [ 7] [ EMERG] [server] Dump rpmsg info between cpu (master: yes)server <==> proxy:
[    0.000000] [ 7] [ EMERG] [server] rpmsg vq RX:
[    0.000000] [ 7] [ EMERG] [server] VQ: rx_vq - size=8; free=0; queued=0; desc_head_idx=32768; available_idx=0; avail.idx=16; used_cons_idx=8; used.idx1
[    0.000000] [ 7] [ EMERG] [server] rpmsg vq TX:
[    0.000000] [ 7] [ EMERG] [server] VQ: tx_vq - size=8; free=5; queued=0; desc_head_idx=3; available_idx=0; avail.idx=6; used_cons_idx=3; used.idx=6; a0
[    0.000000] [ 7] [ EMERG] [server]   rpmsg ept list:
[    0.000000] [ 7] [ EMERG] [server]     ept NS
[    0.000000] [ 7] [ EMERG] [server]     ept rpmsg-sensor
[    0.000000] [ 7] [ EMERG] [server]     ept rpmsg-ping
[    0.000000] [ 7] [ EMERG] [server]     ept rpmsg-syslog
[    0.000000] [ 7] [ EMERG] [server]   rpmsg buffer list:
[    0.000000] [ 7] [ EMERG] [server]     RX buffer, total 8, pending 0
[    0.000000] [ 7] [ EMERG] [server]     TX buffer, total 8, pending 0
[    0.000000] [ 7] [ EMERG] [server] Remote: proxy2 state: 1
[    0.000000] [ 7] [ EMERG] [server] ept NS
[    0.000000] [ 7] [ EMERG] [server] ept rpmsg-sensor
[    0.000000] [ 7] [ EMERG] [server] ept rpmsg-ping
[    0.000000] [ 7] [ EMERG] [server] rpmsg_port queue RX: {used: 0, avail: 8}
[    0.000000] [ 7] [ EMERG] [server] rpmsg buffer list:
[    0.000000] [ 7] [ EMERG] [server] rpmsg_port queue TX: {used: 0, avail: 8}
[    0.000000] [ 7] [ EMERG] [server] rpmsg buffer list:
[    0.000000] [ 7] [ ALERT] [server] sched_dumpstack: backtrace| 5: 0x00000000402a8500 0x00000000402aa1c4 0x000000004029bf78 0x000000004028ca54 0x0000004
[    0.000000] [ 7] [ ALERT] [server] sched_dumpstack: backtrace| 5: 0x00000000402ace74
[    0.000000] [ 7] [ ALERT] [server] sched_dumpstack: backtrace| 6: 0x00000000402a8920 0x00000000402f59a4 0x00000000402bbcb0 0x00000000402bce4c 0x0000004
server> uname -a
NuttX server 12.10.0 455026a7a93-dirty Jan 29 2026 16:27:05 arm64 qemu-armv8a
server> 

[acassis]

@CV-Bowen please include also the patch to be applied to the Linux kernel, this way users will be able to test before we get it integrated on mainline. Please document the steps to get it working

[xiaoxiang781216]

@CV-Bowen please include also the patch to be applied to the Linux kernel, this way users will be able to test before we get it integrated on mainline. Please document the steps to get it working

@acassis why do you request us sharing the source code? The code we upstream to NuttX kernel could ensure NuttX<->NuttX communication correctly, It's our right when/where/how share the code source for other OS publicly.

[acassis]

@CV-Bowen please include also the patch to be applied to the Linux kernel, this way users will be able to test before we get it integrated on mainline. Please document the steps to get it working

@acassis why do you request us sharing the source code? The code we upstream to NuttX kernel could ensure NuttX<->NuttX communication correctly, It's our right when/where/how share the code source for other OS publicly.

@xiaoxiang781216 I think you already shared the source code in the mailing list some time ago. The idea of having it available is to let more people to test it easily.

[xiaoxiang781216]

@CV-Bowen please include also the patch to be applied to the Linux kernel, this way users will be able to test before we get it integrated on mainline. Please document the steps to get it working

@acassis why do you request us sharing the source code? The code we upstream to NuttX kernel could ensure NuttX<->NuttX communication correctly, It's our right when/where/how share the code source for other OS publicly.

@xiaoxiang781216 I think you already shared the source code in the mailing list some time ago.

It's just one or two drivers, but now we have more than 20+ kernel drivers and 10+ Android HAL, it's hard to maintain them by copy.

The idea of having it available is to let more people to test it easily.

The souce code is changing quickly, any code not actively maintained with git by dedicated people will be stale and stop working. So, we can just guarantee and could help NuttX community who are using NuttX<->NuttX IPC, but we don't have additional bandwidth to help the usage on other OS.

[acassis]

@CV-Bowen please include also the patch to be applied to the Linux kernel, this way users will be able to test before we get it integrated on mainline. Please document the steps to get it working

@acassis why do you request us sharing the source code? The code we upstream to NuttX kernel could ensure NuttX<->NuttX communication correctly, It's our right when/where/how share the code source for other OS publicly.

@xiaoxiang781216 I think you already shared the source code in the mailing list some time ago.

It's just one or two drivers, but now we have more than 20+ kernel drivers and 10+ Android HAL, it's hard to maintain them by copy.

The idea of having it available is to let more people to test it easily.

The souce code is changing quickly, any code not actively maintained with git by dedicated people will be stale and stop working. So, we can just guarantee and could help NuttX community who are using NuttX<->NuttX IPC, but we don't have additional bandwidth to help the usage on other OS.

@xiaoxiang781216 understood, so maybe you could keep the current source code in some public place, i.e. github.com/nuttx and then you could keep the modifications updated until it get integrated on Linux. What do you think?

[xiaoxiang781216]

@CV-Bowen please include also the patch to be applied to the Linux kernel, this way users will be able to test before we get it integrated on mainline. Please document the steps to get it working

@acassis why do you request us sharing the source code? The code we upstream to NuttX kernel could ensure NuttX<->NuttX communication correctly, It's our right when/where/how share the code source for other OS publicly.

@xiaoxiang781216 I think you already shared the source code in the mailing list some time ago.

It's just one or two drivers, but now we have more than 20+ kernel drivers and 10+ Android HAL, it's hard to maintain them by copy.

The idea of having it available is to let more people to test it easily.

The souce code is changing quickly, any code not actively maintained with git by dedicated people will be stale and stop working. So, we can just guarantee and could help NuttX community who are using NuttX<->NuttX IPC, but we don't have additional bandwidth to help the usage on other OS.

@xiaoxiang781216 understood, so maybe you could keep the current source code in some public place, i.e. github.com/nuttx and then you could keep the modifications updated until it get integrated on Linux. What do you think?

it will be public on openvela repo: https://github.com/open-vela.

[linguini1]

I don't know if you're also using AI to generate PR descriptions, but please stop including the "Files Changed" section. We can read the diff, it makes your PR take longer to review and adds no information.

[CV-Bowen]

@linguini1 Thanks, Done.