mirror of
https://github.com/apache/nuttx.git
synced 2026-05-25 01:39:44 +08:00
Documentation/rpmsg: add rpmsg dump documentation
Add documentation for the RPMsg dump command, which is a diagnostic tool for dumping RPMsg debugging information. The document covers: - Command usage and syntax - Output description including CPU info, endpoint list, virtqueue dump, and buffer states - Common debugging use cases such as TX buffer timeout issues, communication failures, and buffer leak detection Signed-off-by: Bowen Wang <wangbowen6@xiaomi.com>
This commit is contained in:
Bowen Wang
committed by
Alan C. Assis
Alan C. Assis
parent
5e2b3a114f
commit
97b64010cd
@@ -13,3 +13,4 @@ for inter-processor communication in Asymmetric Multiprocessing (AMP) systems.
|
||||
rpmsg_port
|
||||
rpmsg_port_uart
|
||||
rpmsg_ping
|
||||
rpmsg_dump
|
||||
|
||||
@@ -0,0 +1,199 @@
|
||||
RPMsg Dump
|
||||
==========
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
RPMsg Dump is a diagnostic command for dumping RPMsg debugging information.
|
||||
When troubleshooting inter-processor communication issues, this tool provides
|
||||
detailed information about RPMsg instances, endpoints, virtqueues, and buffer
|
||||
states to assist in debugging.
|
||||
|
||||
This document primarily describes the dump content for **RPMsg VirtIO** transport,
|
||||
which is the most commonly used transport layer.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
Enable the following configuration:
|
||||
|
||||
.. code-block:: makefile
|
||||
|
||||
CONFIG_RPMSG=y
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Command Syntax
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rpmsg dump <path>
|
||||
|
||||
Parameters
|
||||
~~~~~~~~~~
|
||||
|
||||
``<path>``
|
||||
The rpmsg device path. For example, ``/dev/rpmsg/remote``.
|
||||
|
||||
Example Output
|
||||
--------------
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
[12/31 00:01:25] [ 0] [ap] Local: ap Remote: cp Headrx 550 Headtx 504
|
||||
[12/31 00:01:25] [ 0] [ap] Dump rpmsg info between cpu (master: yes)ap <=> cp:
|
||||
[12/31 00:01:25] [ 0] [ap] rpmsg ept list:
|
||||
[12/31 00:01:25] [ 0] [ap] ept NS 0x3c4784d0: addr=53 dest=53 refcnt=1 priority=127 priv=0x3c4784c8
|
||||
[12/31 00:01:25] [ 0] [ap] ept rpmsg-rtc 0x3c3e3428: addr=1024 dest=1033 refcnt=1 priority=127 priv=0x3c37af90
|
||||
[12/31 00:01:25] [ 0] [ap] ept rpmsg-ttyCP 0x3c379e40: addr=1025 dest=1026 refcnt=1 priority=127 priv=0x3c374a00
|
||||
[12/31 00:01:25] [ 0] [ap] ept rpmsg-sensor 0x3c3f4ac8: addr=1028 dest=1028 refcnt=1 priority=127 priv=0x3c3f4ac0
|
||||
[12/31 00:01:25] [ 0] [ap] ept rpmsg-ping 0x3c478418: addr=1029 dest=1031 refcnt=1 priority=127 priv=0
|
||||
[12/31 00:01:25] [ 0] [ap] ept rpmsg-syslog 0x3c3e5818: addr=1034 dest=1025 refcnt=1 priority=127 priv=0x3c3e5810
|
||||
[12/31 00:01:25] [ 0] [ap] rpmsg vq RX:
|
||||
[12/31 00:01:25] [ 0] [ap] VQ: rx_vq - size=16; free=0; queued=0; desc_head_idx=32768; available_idx=0; avail.idx=566; used_cons_idx=550; used.idx=550; avail.flags=0x0; used.flags=0x0
|
||||
[12/31 00:01:25] [ 0] [ap] rpmsg vq TX:
|
||||
[12/31 00:01:25] [ 0] [ap] VQ: tx_vq - size=16; free=6; queued=0; desc_head_idx=10; available_idx=0; avail.idx=504; used_cons_idx=494; used.idx=504; avail.flags=0x0; used.flags=0x0
|
||||
[12/31 00:01:25] [ 0] [ap] rpmsg buffer list:
|
||||
[12/31 00:01:25] [ 0] [ap] RX buffer total 16
|
||||
[12/31 00:01:25] [ 0] [ap] unretrieved 0
|
||||
[12/31 00:01:25] [ 0] [ap] retrieved 0
|
||||
[12/31 00:01:25] [ 0] [ap] pending 0:
|
||||
[12/31 00:01:25] [ 0] [ap] TX buffer total 16
|
||||
[12/31 00:01:25] [ 0] [ap] unretrieved 10
|
||||
[12/31 00:01:25] [ 0] [ap] retrieved 6
|
||||
[12/31 00:01:25] [ 0] [ap] sent 0:
|
||||
|
||||
Output Description
|
||||
------------------
|
||||
|
||||
CPU Information
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
The first section shows basic CPU information:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
Local: ap Remote: cp Headrx 550 Headtx 504
|
||||
Dump rpmsg info between cpu (master: yes)ap <=> cp:
|
||||
|
||||
- **Local/Remote**: Names of the local and remote CPUs
|
||||
- **master**: Indicates whether the current CPU is the master in this RPMsg connection
|
||||
- **Headrx/Headtx**: Counters used for debugging interrupt loss issues
|
||||
(compared with Virtqueue indices in the Virtqueue dump section)
|
||||
|
||||
Endpoint Information
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section lists all endpoints maintained by the current RPMsg instance:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rpmsg ept list:
|
||||
ept NS 0x3c4784d0: addr=53 dest=53 refcnt=1 priority=127 priv=0x3c4784c8
|
||||
ept rpmsg-ttyCP 0x3c379e40: addr=1025 dest=1026 refcnt=1 priority=127 priv=0x3c374a00
|
||||
ept rpmsg-sensor 0x3c3f4ac8: addr=1028 dest=1028 refcnt=1 priority=127 priv=0x3c3f4ac0
|
||||
|
||||
Each endpoint entry contains:
|
||||
|
||||
- **Endpoint Name**: The service name (e.g., ``rpmsg-ttyCP``, ``rpmsg-sensor``)
|
||||
- **Pointer**: Memory address of the endpoint structure
|
||||
- **addr**: Local endpoint address
|
||||
- **dest**: Remote endpoint address (``4294967295`` or ``0xFFFFFFFF`` means not connected)
|
||||
- **refcnt**: Reference count
|
||||
- **priority**: Endpoint priority (0-255, higher value = higher priority)
|
||||
- **priv**: Private data pointer
|
||||
|
||||
Virtqueue Dump
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
This section dumps the core data structures of the Virtqueue:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rpmsg vq RX:
|
||||
VQ: rx_vq - size=16; free=0; queued=0; desc_head_idx=32768; available_idx=0; avail.idx=566; used_cons_idx=550; used.idx=550; avail.flags=0x0; used.flags=0x0
|
||||
rpmsg vq TX:
|
||||
VQ: tx_vq - size=16; free=6; queued=0; desc_head_idx=10; available_idx=0; avail.idx=504; used_cons_idx=494; used.idx=504; avail.flags=0x0; used.flags=0x0
|
||||
|
||||
Key fields:
|
||||
|
||||
- **size**: Total number of descriptors in the virtqueue
|
||||
- **free**: Number of free descriptors
|
||||
- **queued**: Number of queued descriptors
|
||||
- **avail.idx**: Available ring index (producer side)
|
||||
- **used.idx**: Used ring index (consumer side)
|
||||
- **used_cons_idx**: Consumer's view of used ring index
|
||||
|
||||
.. note::
|
||||
|
||||
Generally, you don't need to analyze this section directly.
|
||||
The important information is summarized in the RPMsg Buffer List section below.
|
||||
|
||||
RPMsg Buffer List
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section provides a summary of RX/TX buffer states:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
rpmsg buffer list:
|
||||
RX buffer total 16
|
||||
unretrieved 0
|
||||
retrieved 0
|
||||
pending 0:
|
||||
TX buffer total 16
|
||||
unretrieved 10
|
||||
retrieved 6
|
||||
sent 0:
|
||||
|
||||
**RX Buffer States:**
|
||||
|
||||
- **total**: Total number of RX buffers
|
||||
- **unretrieved**: Buffers received and in RX queue, not yet retrieved
|
||||
- **retrieved**: Buffers retrieved from RX queue but not yet returned
|
||||
- **pending**: Buffers pending processing
|
||||
|
||||
**TX Buffer States:**
|
||||
|
||||
- **total**: Total number of TX buffers
|
||||
- **unretrieved**: Number of free TX buffers available
|
||||
- **retrieved**: Buffers retrieved from free pool but not yet sent
|
||||
- **sent**: Buffers sent but not yet returned by remote side
|
||||
|
||||
Debugging Use Cases
|
||||
-------------------
|
||||
|
||||
TX Buffer Timeout Issues
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
When a thread fails to acquire a TX buffer (timeout), check:
|
||||
|
||||
1. **Remote RX thread state**: Is it blocked on a semaphore/mutex (possible deadlock)?
|
||||
2. **Remote RX thread ready but not running**: Check CPU load - higher priority tasks
|
||||
may be starving the RX thread
|
||||
3. **Remote RX thread waiting but RX queue has data**: Compare ``Headrx`` with
|
||||
virtqueue indices to check for interrupt loss
|
||||
|
||||
Communication Not Working
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. **Check if RPMsg thread exists**: Use ``ps`` command to verify thread presence
|
||||
2. **Check if RPMsg instance exists**: List ``/dev/rpmsg/`` directory
|
||||
3. **Use RPMsg Ping**: Test basic connectivity with ``rpmsg ping`` command
|
||||
4. **Check endpoint dest address**: If ``dest=4294967295``, the endpoint is not
|
||||
connected to the remote side
|
||||
|
||||
Buffer Leak Detection
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If ``retrieved`` count keeps increasing over time without corresponding
|
||||
``unretrieved`` increase, there may be a buffer leak where buffers are
|
||||
being acquired but not properly released.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`concepts` - RPMsg core concepts
|
||||
- :doc:`rpmsg_ping` - RPMsg connectivity testing tool
|
||||
Reference in New Issue
Block a user