ROS 2 Agnocast

An rclcpp-compatible true zero-copy IPC middleware that supports all ROS message types, including message structs already generated by rosidl.

This middleware is based on the following paper and the corresponding prototype. The paper has been accepted to IEEE ISORC 2025 (pdf).

T. Ishikawa–Aso and S. Kato, “ROS 2 Agnocast: Supporting Unsized Message Types for True Zero-Copy Publish/Subscribe IPC,” in Proc. 28th Int. Symp. Real-Time Distributed Computing (ISORC), 2025, pp. 1–10.

<details> <summary>BibTeX</summary>

@inproceedings{ishikawa2025ros,
  title={ROS 2 Agnocast: Supporting Unsized Message Types for True Zero-Copy Publish/Subscribe IPC},
  author={Ishikawa--Aso, Takahiro and Kato, Shinpei},
  booktitle={2025 28th International Symposium on Real-Time Distributed Computing (ISORC)},
  pages={01--10},
  year={2025},
  organization={IEEE}
}

</details>

Supported Environments
For Users
For Developers
Debug
Troubleshooting
Documents

Supported Environments

Agnocast is currently available in the following environments. This reflects the current status, and support is expected to expand in the future.

| Category | Supported Versions / Notes | |--------------------|--------------------------------------------------------------| | ROS 2 | Humble / Jazzy (only with rclcpp client library) | | Linux Distribution | Ubuntu 22.04 (Jammy) / Ubuntu 24.04 (Noble) | | Linux Kernel | 5.x / 6.x series (detailed version matrix not yet available) |

Warning: Agnocast service/client is not officially supported yet and the API may change in the future. Use at your own risk.

For Users

For installation, setup, and usage instructions, please refer to the Getting Started Guide.

For Developers

Clone the repository

Clone the latest main branch for development:

git clone https://github.com/autowarefoundation/agnocast.git
cd agnocast

Setup

Run the setup script to install dependencies:

bash scripts/setup.bash

Setup pre-commit

The following command allows clang-format, markdownlint, and KUNIT Test to be run before each commit.

python3 -m pip install pre-commit
python3 -m pip install --upgrade pre-commit identify
pre-commit install

If you want to disable pre-commit, please run pre-commit uninstall.

Build and insert kmod

Build.

bash scripts/build_all.bash

Check if there is a libagnocast_heaphook.so in install/agnocastlib/lib.

$ ls install/agnocastlib/lib | grep libagnocast_heaphook
libagnocast_heaphook.so

Insert kernel module.

cd agnocast_kmod
sudo insmod agnocast.ko
sudo lsmod

Test

You can build, test and generate the coverage report by following:

bash scripts/test/test_and_create_report.bash

Kernel Module Test

A custom kernel with the following CONFIG enabled is required to run KUnit Test and obtain the coverage report (sample custom kernel is placed here).

CONFIG_KUNIT=y
CONFIG_GCOV_KERNEL=y

If booting with the custom kernel, the following script can be used to run unit tests on kernel modules and generate coverage reports.

bash scripts/test/run_kunit.bash

You can also use pre-commit

Debug

Check the kernel log.

sudo dmesg -w

To use dynamic_debug for dynamically outputting debug logs, please run the following command as super user:

sudo su
echo 'file agnocast_main.c +p' > /sys/kernel/debug/dynamic_debug/control

Check if dynamic_debug is enabled by running the following command. If the right side of the = is p, it is enabled. (If it's _, it is disabled.)

sudo cat /sys/kernel/debug/dynamic_debug/control | grep "agnocast_main.c"
/.../agnocast/agnocast_kmod/agnocast_main.c:810 [agnocast]release_msgs_to_meet_depth =p "Release oldest message in the publisher_queue (publisher_pid=%d) of the topic (topic_name=%s) with qos_depth %d. (release_msgs_to_meet_depth)\012"
/.../agnocast/agnocast_kmod/agnocast_main.c:367 [agnocast]insert_message_entry =p "Insert an entry (topic_name=%s publisher_pid=%d msg_virtual_address=%lld timestamp=%lld). (insert_message_entry)"

To use dynamic_debug, the Linux kernel configuration must have CONFIG_DYNAMIC_DEBUG set to y. If CONFIG_DYNAMIC_DEBUG is not enabled in your environment, perform a debug build with:

make CFLAGS_agnocast.o="-DDEBUG"

Refer to the Linux kernel documentation on kbuild for more information about compilation flags.

Troubleshooting

Shared memory and message queue cleanup

Agnocast spawns a background daemon process (forked from the first Agnocast process) that automatically cleans up shared memory and message queues when processes exit. The daemon inherits the parent's process name, so broad kill commands like killall or kill -9 $(pgrep -f ...) may accidentally kill it along with application processes. If the daemon dies, cleanup stops and resources will leak. To avoid this, stop application processes individually (e.g., with Ctrl+C or by targeting specific PIDs).

If shared memory or message queues are left behind, you can remove them manually:

# Remove leftover shared memory
rm /dev/shm/agnocast@*

# Remove leftover message queues
rm /dev/mqueue/agnocast@*
rm /dev/mqueue/agnocast_bridge_manager@*

If you encounter mq_open failed: No space left on device, the system has reached the maximum number of message queues. Run the cleanup commands above, and if the error persists, increase the system-wide queues_max limit (e.g., sudo sysctl -w fs.mqueue.queues_max=1024). See System Configuration for details.

Agnocast

Install / Use

README