LibCyphal Reference Implementation

The Presentation layer is the primary interface for interacting with DSDL-generated types. It uses a non-polymorphic, non-generic controller class called Presentation to manage port objects.

Key Concepts:

• Port Objects: The layer provides four types of ports: Publishers, Subscribers, RPC Clients, and RPC Servers.
• Lifecycle & Resource Management:
  • Port objects (publishers/subscribers/clients) are returned by value.
  • Multiple ports on the same port-ID share a single, hidden, heap-allocated implementation object. This object is destroyed only when the last port using that port-ID is destroyed.
  • To avoid runtime costs, de-initialization of transport sessions is postponed until the next IRunnable::run cycle.
• Polymorphism: Unlike many C++ libraries that rely heavily on template metaprogramming, LibCyphal prefers runtime polymorphism for DSDL types. Generated types implement the IComposite interface to support runtime type identification and serialization/deserialization.

class IComposite : public cetl::IPolymorphicType
{
public:
    [[nodiscard]] virtual SerializeResult _serialize_(cetl::bitspan out_buffer) const = 0;
    [[nodiscard]] virtual SerializeResult _deserialize_(cetl::const_bitspan in_buffer) = 0;
    [[nodiscard]] virtual std::string_view _getFullName_() const noexcept = 0;
    [[nodiscard]] virtual std::string_view _getFullNameAndVersion_() const noexcept = 0;

protected:
    IComposite() = default;
    virtual ~IComposite() noexcept = default;
};

The Registry (implementing IRegistry and IIntrospectableRegistry) allows you to manage a collection of named registers. Registers are accessed by name (using a 64-bit hash for efficiency) and provide a way to get or set values.

Core Interfaces

• IRegistry: Provides get(name) and set(name, value) methods. get returns a ValueWithMetadata (containing the value and RegisterFlags), and set returns an optional SetError.
• IIntrospectableRegistry: Extends IRegistry with index(index) and size() to allow iterating over the register set.

Register Flags

• mutable_: Indicates if the register can be changed via set().
• persistent: Indicates if the register value should be retained across application restarts.

SetError Codes

• Existence: Register does not exist.
• Mutability: Register is immutable.
• Coercion: Value cannot be coerced to the register type.
• Semantics: Rejected by register semantics (e.g., out of range).

// Example of the basic interface
std::optional<ValueWithMetadata> val = registry.get("my_register");
if (val) {
    // use val->value
}

std::optional<SetError> err = registry.set("my_register", dsdl_val);
if (!err) {
    // success
}

To avoid dependency on opaque compiler-generated RTTI code and to support environments where RTTI is disabled, LibCyphal uses a substitute mechanism for type identity.

Important Limitation: The primary substitute relies on the address of a static local variable in an inline function. While this is guaranteed to be unique within a single executable, dynamic linking (shared objects) can break this, as different shared objects may have their own instantiations of the type ID. If the library is used across dynamically linked boundaries, RTTI support (LIBCYPHAL_USE_RTTI) should be enabled to ensure correctness.

/// A simplified substitute for RTTI that allows querying the identity of types.
/// Returns an object of an unspecified type for which operator== and operator!= are defined.
/// Objects for the same type compare equal. Ordering is not defined.
template <typename>
auto getTypeID() noexcept
{
    static const struct {} placeholder{};
    return static_cast<const void*>(&placeholder);
}
using TypeID = decltype(getTypeID<void>());

LibCyphal is organized into three distinct functional layers that build upon one another:

1. libcyphal::transport: The lowest layer. It abstracts the underlying "lizards" via the ITransport interface. At this level, data is handled as serialized binary blobs. It provides the glue logic between the transport protocols and the platform layer.
2. libcyphal::presentation: The middle layer. It sits on top of the transport layer and provides:
   • DSDL (de)serialization (using Nunavut-generated code) so users can work with DSDL objects instead of raw blobs.
   • Demultiplexing of incoming transfers, allowing multiple subscribers to a single subject.
   • An interface for invoking and serving RPC service calls.
3. libcyphal::application: The top layer. It provides a node-centric API and implements standard protocol functions like the register interface, heartbeat publication, and port usage messages. This layer depends on Nunavut-generated code from standard DSDL definitions.

LibCyphal uses an execution model based on the IRunnable interface. To perform asynchronous operations (like servicing a transport), you must periodically call run(now: TimePoint).

For managing multiple runnable entities in a single thread, use AggregateRunnable. This class implements IRunnable itself and allows you to register/unregister multiple inferior runnables.

Note on I/O Multiplexing: The library supports two execution strategies:

1. Stateless (IPollSet): Reconstructs the poll set from scratch every cycle. Good for simple poll/select loops.
2. Stateful (IMultiplexer): Maintains a persistent set of pollable entities, allowing efficient use of epoll or kqueue. This uses RAII Handle objects to manage pollable lifetimes.

template <std::size_t Capacity>
class AggregateRunnable final : public IRunnable
{
public;
    /// Invokes run() on all members in an unspecified order.
    void run(const TimePoint now, IPollSet& poll_set) override;
    /// Returns true on success, false if the capacity is exhausted.
    [[nodiscard]] bool add(IRunnable& inferior);
    /// Returns true if such inferior was found and removed, false if not found.
    [[nodiscard]] bool remove(IRunnable& inferior);
};