Build zero-copy `UTransport`

[PLeVasseur]

Why a zero-copy transport for uProtocol?

• It's very common in Advanced Driver-Assistance Systems (ADAS) / Automated Driving (AD) systems to have large messages which are being sent around, including large camera images and point cloud data from LIDARs
• It's becoming common in automotive systems to have a gateway concept where inter-device communication flows into each device's gateway over a different transport (e.g. SOME/IP, CAN) and is then copied into shared-memory to allow zero-copy publishes to consumers
• By providing a zero-copy UTransport we open up uProtocol to the ADAS / AD domains and wider adoption in OEMs / integrators which desire this functionality in a gateway

Main goals

Implement a zero-copy UTransport where the UMessage is not copied from sender to receiver but is passed on by means of a shared memory reference only (or equivalent mechanism).

• In a first step, use the existing Protobuf encoding of UMessage to serialize the message to an (opaque) byte array which can then be passed on by means of a shared memory reference.
• In a second step, figure out what it would take to avoid serialization and deserialization of UMessage altogether, even across programming languages. This will most certainly require the sender and receiver implementations to have the same understanding of how memory is laid out for a particular data structure.
• In a third step, implement the zero-copy, no-serialization approach.

Constraints

• Use iceoryx2 to implement the zero-copy transport, as it is a forward-looking solution and is headed for ASIL-D safety-qualification

Desired outcomes

• A Rust based UTransport implementation (up-transport-iceoryx2-rust crate) which can be published to crates.io.

Extra integration into uProtocol ecosystem

• Show integration of up-transport-iceoryx2-rust into up-streamer-rust reference implementation
• Attempt to use the Eclipse Zenoh shared-memory transport option
  • Interesting to ask: Why did Eclipse Zenoh choose not to use iceoryx2?
• Create a C-based implementation of the zero-copy transport (up-transport-iceoryx2-c)
• Show interoperability between up-transport-iceoryx2-rust and up-transport-iceoryx-c
  • Use Gherkin feature files to show compatibility as is being done for up-rust tests

Additional resources

Eclipse Foundation

• Eclipse Contributor Agreement
• To actually sign it go here

Rust

Mindset

• Rust in 2025: Targeting foundational software

Typical community suggestions

• The Rust Programming Language
• Rust by Example
• rustlings

Things also sometimes recommended, maybe more niche

• Learn Rust With Entirely Too Many Linked Lists
• Learn Rust the Dangerous Way

iceoryx2

How does iceoryx2 allow for zero-copy shared memory understanding of memory layout between languages? Doesn't each language have different memory layouts and representation?

True! So in the iceoryx ecosystem they have libraries for languages which allow a common understanding:

• Rust: iceoryx2_bb_container - link to docs
• C++: iceoryx hoofs

Getting started with iceoryx2

• Great to start with the docs on crates.io!
• Consider building their examples and experimenting with them

Eclipse uProtocol - Topology

There's a somewhat outdated, but still conceptually relevant diagram in the uProtocol Roadmap.

Generally speaking, unless constraints would prevent otherwise, within a single logical or physical system, a zero-copy / shared memory transport should be used (the black lines in the diagram). Between logical or physical systems, other mechanisms are used as appropriate.

The uStreamer is used as a protocol bridging library and service to allow the transition to/from different underlying protocols.

UTransport

• Here's a link to the up-rust UTransport trait.
• There are existing implementations
  • up-transport-mqtt5-rust
  • up-transport-zenoh-rust
  • up-transport-vsomeip-rust - the most complicated since it involved interop between C++ <=> Rust, so don't start here 🙂

[stevenhartley]

Here are some good "getting started" references for you to watch/read:

• https://uprotocol.org/
• https://uprotocol.org/media/ (watch the videos at the bottom and read the articles)

[PLeVasseur]

Goals for Week 2 - ending 2025-06-06

• [x] @stevenhartley to get ticket resolved and have up-transport-iceoryx2-rust repo created
• [ ] @PLeVasseur to look into mapping from URI <=> iceoryx2 addressing scheme
• [ ] Students create up-transport-iceoryx2-rust repo for now under one of their names and work from there
• [ ] Students set up their local development environment for Rust (using rustup)
• [ ] Students to clone the iceoryx2 repo, run and read the Rust examples
  • An important step when starting to work with a new project
• [ ] Students to create the up-transport-iceoryx2-rust library crate with the necessary dependencies to the Cargo.toml of their up-transport-iceoryx2-rust crate
  • The Rust Programming Language book has a section on how to start a new Cargo project
  • Probably need for dependencies at a minimum up-rust and iceoryx2
  • The Rust Programming Language book also has a part about how to fill the [dependencies] section of the Cargo.toml
• [ ] Students to stub an implementation of an Iceoryx2Transport struct. Consider what kinds of state needs to be held by the Iceoryx2Transport.
• [ ] Students to stub an implemention of the up-rust UTransport trait for Iceoryx2Transport struct which does nothing for now
  • Examples can be found above under the body of the top comment on this issue
• [ ] Students to read the section of The Rust Programming language about testing
  • Rust has first-class tooling for both unit and integration tests
  • It's an expectation of the uProtocol project that testing is used to test correctness and prevent regressions
• [ ] Students to copy @AnotherDaniel's excellent check.yml into the ./github/ folder of their new repo as a starting point and modify as necessary such that this GitHub action will be fired upon PRs attempting to be merged
  • Software projects like these have automated tests which will run upon a Pull Request being opened to let others know before merging if there have been any regressions
• [ ] Students to write some "dummy" passing and failing tests to confirm that the check workflow is properly running on PRs being opened and reporting status correctly