feat: add red/blue logical Sesame channels and Echo service channel routing

documents/modules/ROOT/pages/CodingStandard.adoc

@@ -530,6 +530,8 @@ So even though both parameters start with typename, the first parameter takes a
 
 When in doubt, disable each warning that pops up, because our unit tests are far better suited at communicating whether your code is correct or not.
 
+When intentionally keeping a parameter or local variable unused, prefer `[[maybe_unused]]` over `static_cast<void>(value)`.
+
 [NOTE]
 Platform software such as CMSIS often produces warnings out-of-the-box. Since this code is most often written in C, and since we usually do not write code in C, consider disabling all warnings for the C language.
 

documents/modules/ROOT/pages/Sesame.adoc

@@ -49,13 +49,14 @@ for details.
 == SESAME layer Windowed
 
 Using the Windowed layer, both sides of the communication notify and update their peer of
-available window size. A peer can only send packets up to the available window. Four
+available window size. A peer can only send packets up to the available window. Five
 packet types are defined:
 
 1. Init
 2. InitResponse
 3. ReleaseWindow
-4. Message
+4. MessageRed
+5. MessageBlue
 
 === Init
 
@@ -122,9 +123,9 @@ freed up in addition to already known free space.
 (draw-box "size" {:span 2})
 ----
 
-=== Message
+=== MessageRed and MessageBlue
 
-Data sent by higher protocol layers are sent by `Message` packets. Each `Message` packet consumes a window
+Data sent by higher protocol layers are sent by `MessageRed` (`identifier 4`) and `MessageBlue` (`identifier 5`) packets. Each message packet consumes a window
 amount equal to the size of that packet plus the COBS overhead of that specific packet, plus
 its terminating 0.
 
@@ -133,7 +134,7 @@ its terminating 0.
 ----
 (def boxes-per-row 8)
 (draw-column-headers)
-(draw-box 4)
+(draw-box "4 or 5")
 (draw-gap "message")
 (draw-bottom)
 ----

protobuf/echo/Echo.cpp

@@ -8,14 +8,30 @@ namespace services
         Rpc().ServiceDone();
     }
 
+    Service::Service(Echo& echo, EchoChannel channel)
+        : infra::Observer<Service, Echo>(echo)
+        , channel(channel)
+    {}
+
+    EchoChannel Service::Channel() const
+    {
+        return channel;
+    }
+
+    void Service::SetChannel(EchoChannel channel)
+    {
+        this->channel = channel;
+    }
+
     Echo& Service::Rpc()
     {
         return Subject();
     }
 
-    ServiceProxy::ServiceProxy(Echo& echo, uint32_t maxMessageSize)
+    ServiceProxy::ServiceProxy(Echo& echo, uint32_t maxMessageSize, EchoChannel channel)
         : echo(echo)
         , maxMessageSize(maxMessageSize)
+        , channel(channel)
     {}
 
     ServiceProxy::~ServiceProxy()
@@ -65,6 +81,16 @@ namespace services
         return currentRequestedSize;
     }
 
+    EchoChannel ServiceProxy::Channel() const
+    {
+        return channel;
+    }
+
+    void ServiceProxy::SetChannel(EchoChannel channel)
+    {
+        this->channel = channel;
+    }
+
     void ServiceProxy::SetSerializer(const infra::SharedPtr<MethodSerializer>& serializer)
     {
         methodSerializer = serializer;

protobuf/echo/Echo.hpp

@@ -6,9 +6,16 @@
 #include "infra/util/Observer.hpp"
 #include "protobuf/echo/EchoErrorPolicy.hpp"
 #include "protobuf/echo/Serialization.hpp"
+#include <cstdint>
 
 namespace services
 {
+    enum class EchoChannel : uint8_t
+    {
+        red = 0,
+        blue = 1
+    };
+
     class Echo;
     class Service;
     class ServiceProxy;
@@ -18,21 +25,27 @@ namespace services
     {
     public:
         using infra::Observer<Service, Echo>::Observer;
+        Service(Echo& echo, EchoChannel channel = EchoChannel::red);
 
         virtual bool AcceptsService(uint32_t id) const = 0;
+        EchoChannel Channel() const;
+        void SetChannel(EchoChannel channel);
 
         void MethodDone();
         virtual infra::SharedPtr<MethodDeserializer> StartMethod(uint32_t serviceId, uint32_t methodId, uint32_t size, const EchoErrorPolicy& errorPolicy) = 0;
 
     protected:
         Echo& Rpc();
+
+    private:
+        EchoChannel channel = EchoChannel::red;
     };
 
     class ServiceProxy
         : public infra::IntrusiveList<ServiceProxy>::NodeType
     {
     public:
-        ServiceProxy(Echo& echo, uint32_t maxMessageSize);
+        ServiceProxy(Echo& echo, uint32_t maxMessageSize, EchoChannel channel = EchoChannel::red);
 
         Echo& Rpc();
         virtual void RequestSend(infra::Function<void()> onGranted);
@@ -41,6 +54,8 @@ namespace services
         void CancelRequestSend();
         uint32_t MaxMessageSize() const;
         uint32_t CurrentRequestedSize() const;
+        EchoChannel Channel() const;
+        void SetChannel(EchoChannel channel);
         void SetSerializer(const infra::SharedPtr<MethodSerializer>& serializer);
 
     protected:
@@ -49,6 +64,7 @@ namespace services
     private:
         Echo& echo;
         uint32_t maxMessageSize;
+        EchoChannel channel = EchoChannel::red;
         infra::AutoResetFunction<void()> onGranted;
         uint32_t currentRequestedSize = 0;
         infra::SharedPtr<MethodSerializer> methodSerializer;

protobuf/echo/EchoOnStreams.cpp

@@ -152,6 +152,7 @@ namespace services
                                + 2 * infra::MaxVarIntSize(std::numeric_limits<uint64_t>::max()); // echo framing overhead (service and method id)
 
             sendRequesters.pop_front();
+            SendingProxySelected(*sendingProxy);
             RequestSendStream(sendingProxySize);
         }
     }
@@ -161,6 +162,10 @@ namespace services
         return proxy.GrantSend();
     }
 
+    void EchoOnStreams::SendingProxySelected([[maybe_unused]] ServiceProxy& proxy)
+    {
+    }
+
     infra::SharedPtr<MethodDeserializer> EchoOnStreams::StartingMethod(uint32_t serviceId, uint32_t methodId, infra::SharedPtr<MethodDeserializer>&& deserializer)
     {
         return std::move(deserializer);

protobuf/echo/EchoOnStreams.hpp

@@ -35,6 +35,7 @@ namespace services
     protected:
         void Reset();
         virtual infra::SharedPtr<MethodSerializer> GrantSend(ServiceProxy& proxy);
+        virtual void SendingProxySelected(ServiceProxy& proxy);
         virtual infra::SharedPtr<MethodDeserializer> StartingMethod(uint32_t serviceId, uint32_t methodId, infra::SharedPtr<MethodDeserializer>&& deserializer);
         virtual void RequestSendStream(std::size_t size) = 0;
 

protobuf/echo/test/TestEcho.cpp

@@ -72,3 +72,17 @@ TEST_F(EchoTest, cancel_and_retry_request_send_succeeds)
     serviceProxy.GrantSend();
     EXPECT_TRUE(granted);
 }
+
+TEST_F(EchoTest, service_proxy_channel_is_configurable_via_constructor)
+{
+    services::ServiceStubProxy blueProxy{ echo, services::EchoChannel::blue };
+
+    EXPECT_THAT(blueProxy.Channel(), testing::Eq(services::EchoChannel::blue));
+}
+
+TEST_F(EchoTest, service_channel_is_configurable_via_constructor)
+{
+    testing::StrictMock<services::ServiceStub> blueService{ echo, services::EchoChannel::blue };
+
+    EXPECT_THAT(blueService.Channel(), testing::Eq(services::EchoChannel::blue));
+}

protobuf/echo/test_doubles/ServiceStub.cpp

@@ -50,8 +50,8 @@ namespace services
         return value;
     }
 
-    ServiceStub::ServiceStub(Echo& echo)
-        : Service(echo)
+    ServiceStub::ServiceStub(Echo& echo, EchoChannel channel)
+        : Service(echo, channel)
     {}
 
     bool ServiceStub::AcceptsService(uint32_t id) const
@@ -84,8 +84,8 @@ namespace services
         }
     }
 
-    ServiceStubProxy::ServiceStubProxy(services::Echo& echo)
-        : services::ServiceProxy(echo, maxMessageSize)
+    ServiceStubProxy::ServiceStubProxy(services::Echo& echo, EchoChannel channel)
+        : services::ServiceProxy(echo, maxMessageSize, channel)
     {}
 
     void ServiceStubProxy::Method(uint32_t value)

protobuf/echo/test_doubles/ServiceStub.hpp

@@ -64,7 +64,7 @@ namespace services
         : public services::Service
     {
     public:
-        ServiceStub(Echo& echo);
+        ServiceStub(Echo& echo, EchoChannel channel = EchoChannel::red);
 
         bool AcceptsService(uint32_t id) const override;
 
@@ -90,7 +90,7 @@ namespace services
         : public services::ServiceProxy
     {
     public:
-        ServiceStubProxy(services::Echo& echo);
+        ServiceStubProxy(services::Echo& echo, EchoChannel channel = EchoChannel::red);
 
     public:
         void Method(uint32_t value);

protobuf/protoc_echo_plugin/ProtoCEchoPlugin.cpp

@@ -1160,7 +1160,12 @@ namespace application
         auto constructor = std::make_shared<Constructor>(service->name, "", 0);
         constructor->Parameter("services::Echo& echo");
         constructor->Initializer("services::Service(echo)");
+        constructors->Add(constructor);
 
+        constructor = std::make_shared<Constructor>(service->name, "", 0);
+        constructor->Parameter("services::Echo& echo");
+        constructor->Parameter("services::EchoChannel channel");
+        constructor->Initializer("services::Service(echo, channel)");
         constructors->Add(constructor);
         serviceFormatter->Add(constructors);
     }
@@ -1171,7 +1176,12 @@ namespace application
         auto constructor = std::make_shared<Constructor>(service->name + "Proxy", "", 0);
         constructor->Parameter("services::Echo& echo");
         constructor->Initializer("services::ServiceProxy(echo, maxMessageSize)");
+        constructors->Add(constructor);
 
+        constructor = std::make_shared<Constructor>(service->name + "Proxy", "", 0);
+        constructor->Parameter("services::Echo& echo");
+        constructor->Parameter("services::EchoChannel channel");
+        constructor->Initializer("services::ServiceProxy(echo, maxMessageSize, channel)");
         constructors->Add(constructor);
         serviceProxyFormatter->Add(constructors);
     }

services/echo_console/Main.cpp

@@ -36,8 +36,8 @@ class ConsoleClientUart
 private:
     // Implementation of SesameObserver
     void Initialized() override;
-    void SendMessageStreamAvailable(infra::SharedPtr<infra::StreamWriter>&& writer) override;
-    void ReceivedMessage(infra::SharedPtr<infra::StreamReaderWithRewinding>&& reader) override;
+    void SendMessageStreamAvailable(infra::SharedPtr<infra::StreamWriter>&& writer, [[maybe_unused]] services::SesameChannel channel) override;
+    void ReceivedMessage(infra::SharedPtr<infra::StreamReaderWithRewinding>&& reader, [[maybe_unused]] services::SesameChannel channel) override;
 
 private:
     void CheckDataToBeSent();
@@ -92,7 +92,7 @@ void ConsoleClientUart::Initialized()
         });
 }
 
-void ConsoleClientUart::SendMessageStreamAvailable(infra::SharedPtr<infra::StreamWriter>&& writer)
+void ConsoleClientUart::SendMessageStreamAvailable(infra::SharedPtr<infra::StreamWriter>&& writer, [[maybe_unused]] services::SesameChannel channel)
 {
     infra::DataOutputStream::WithErrorPolicy stream(*writer);
     stream << infra::StringAsByteRange(infra::BoundedConstString(messagesToBeSent.front()));
@@ -104,7 +104,7 @@ void ConsoleClientUart::SendMessageStreamAvailable(infra::SharedPtr<infra::Strea
     CheckDataToBeSent();
 }
 
-void ConsoleClientUart::ReceivedMessage(infra::SharedPtr<infra::StreamReaderWithRewinding>&& reader)
+void ConsoleClientUart::ReceivedMessage(infra::SharedPtr<infra::StreamReaderWithRewinding>&& reader, [[maybe_unused]] services::SesameChannel channel)
 {
     ConsoleObserver::Subject().DataReceived(*reader);
 }

services/tracer/TracingEchoInstantiation.cpp

@@ -4,7 +4,7 @@ namespace main_
 {
     TracingEchoOnSesame::TracingEchoOnSesame(Sesame::CobsStorageBase& storage, hal::BufferedSerialCommunication& serialCommunication, services::MethodSerializerFactory& serializerFactory, services::Tracer& tracer)
         : cobs(storage.cobsSendStorage, storage.cobsReceivedMessage, serialCommunication)
-        , windowed(storage.windowedReceivedMessage, storage.windowedReceiveBuffers, cobs)
+        , windowed(storage.windowedRedReceivedMessage, storage.windowedBlueReceivedMessage, storage.windowedReceiveBuffers, cobs)
         , echo(serializerFactory, services::echoErrorPolicyAbort, tracer, windowed)
     {}
 

services/tracer/TracingEchoInstantiationSecured.cpp

@@ -5,7 +5,7 @@ namespace main_
 {
     TracingEchoOnSesameSecured::TracingEchoOnSesameSecured(Sesame::CobsStorageBase& storage, infra::BoundedVector<uint8_t>& securedSendBuffer, infra::BoundedVector<uint8_t>& securedReceiveBuffer, hal::BufferedSerialCommunication& serialCommunication, services::MethodSerializerFactory& serializerFactory, const services::SesameSecured::KeyMaterial& keyMaterial, services::Tracer& tracer, const services::EchoErrorPolicy& echoErrorPolicy, services::SesameInitializer& initializer)
         : cobs(storage.cobsSendStorage, storage.cobsReceivedMessage, serialCommunication)
-        , windowed(storage.windowedReceivedMessage, storage.windowedReceiveBuffers, cobs, initializer)
+        , windowed(storage.windowedRedReceivedMessage, storage.windowedBlueReceivedMessage, storage.windowedReceiveBuffers, cobs, initializer)
         , secured(securedSendBuffer, securedReceiveBuffer, windowed, keyMaterial)
         , echo(serializerFactory, echoErrorPolicy, tracer, secured)
     {}

services/tracer/TracingSesameWindowed.cpp

@@ -2,8 +2,8 @@
 
 namespace services
 {
-    TracingSesameWindowed::TracingSesameWindowed(infra::BoundedDeque<uint8_t>& receivedMessage, uint8_t splitBuffers, SesameEncoded& delegate, Tracer& tracer, SesameInitializer& sesameInitializer)
-        : SesameWindowed(receivedMessage, splitBuffers, delegate, sesameInitializer)
+    TracingSesameWindowed::TracingSesameWindowed(infra::BoundedDeque<uint8_t>& redReceivedMessage, infra::BoundedDeque<uint8_t>& blueReceivedMessage, uint8_t splitBuffers, SesameEncoded& delegate, Tracer& tracer, SesameInitializer& sesameInitializer)
+        : SesameWindowed(redReceivedMessage, blueReceivedMessage, splitBuffers, delegate, sesameInitializer)
         , tracer(tracer)
     {}
 
@@ -51,9 +51,9 @@ namespace services
         tracer.Trace() << "SesameWindowed::SendingReleaseWindow deltaWindow: " << deltaWindow;
     }
 
-    void TracingSesameWindowed::SendingMessage(infra::StreamWriter& writer)
+    void TracingSesameWindowed::SendingMessage([[maybe_unused]] infra::StreamWriter& writer, SesameChannel channel)
     {
-        tracer.Trace() << "SesameWindowed::SendingMessage";
+        tracer.Trace() << "SesameWindowed::SendingMessage channel: " << (channel == SesameChannel::red ? "red" : "blue");
     }
 
     void TracingSesameWindowed::SettingOperational(std::optional<std::size_t> requestedSize, uint16_t releasedWindow, uint16_t otherWindow)

services/tracer/TracingSesameWindowed.hpp

@@ -13,7 +13,7 @@ namespace services
         template<std::size_t MaxMessageSize, uint8_t SplitBuffers = 2>
         struct WithMaxMessageSize;
 
-        TracingSesameWindowed(infra::BoundedDeque<uint8_t>& receivedMessage, uint8_t splitBuffers, SesameEncoded& delegate, Tracer& tracer, SesameInitializer& sesameInitializer = immediatelyGranted);
+        TracingSesameWindowed(infra::BoundedDeque<uint8_t>& redReceivedMessage, infra::BoundedDeque<uint8_t>& blueReceivedMessage, uint8_t splitBuffers, SesameEncoded& delegate, Tracer& tracer, SesameInitializer& sesameInitializer = immediatelyGranted);
 
     protected:
         void ReceivedInit(uint16_t newWindow) override;
@@ -24,7 +24,7 @@ namespace services
         void SendingInit(uint16_t newWindow) override;
         void SendingInitResponse(uint16_t newWindow) override;
         void SendingReleaseWindow(uint16_t deltaWindow) override;
-        void SendingMessage(infra::StreamWriter& writer) override;
+        void SendingMessage(infra::StreamWriter& writer, SesameChannel channel) override;
         void SettingOperational(std::optional<std::size_t> requestedSize, uint16_t releasedWindow, uint16_t otherWindow) override;
 
     private:
@@ -33,12 +33,12 @@ namespace services
 
     template<std::size_t MaxMessageSize, uint8_t SplitBuffers>
     struct TracingSesameWindowed::WithMaxMessageSize
-        : infra::WithStorage<TracingSesameWindowed, infra::BoundedDeque<uint8_t>::WithMaxSize<receiveBufferSize<MaxMessageSize, SplitBuffers>>>
+        : infra::WithStorage<infra::WithStorage<TracingSesameWindowed, infra::BoundedDeque<uint8_t>::WithMaxSize<receiveBufferSize<MaxMessageSize, SplitBuffers>>>, infra::BoundedDeque<uint8_t>::WithMaxSize<receiveBufferSize<MaxMessageSize, SplitBuffers>>>
     {
         static_assert(SplitBuffers >= 2, "SesameWindowed requires at least 2 receive buffers");
 
         WithMaxMessageSize(SesameEncoded& delegate, Tracer& tracer, SesameInitializer& sesameInitializer = immediatelyGranted)
-            : infra::WithStorage<TracingSesameWindowed, infra::BoundedDeque<uint8_t>::WithMaxSize<receiveBufferSize<MaxMessageSize, SplitBuffers>>>::WithStorage(SplitBuffers, delegate, tracer, sesameInitializer)
+            : infra::WithStorage<infra::WithStorage<TracingSesameWindowed, infra::BoundedDeque<uint8_t>::WithMaxSize<receiveBufferSize<MaxMessageSize, SplitBuffers>>>, infra::BoundedDeque<uint8_t>::WithMaxSize<receiveBufferSize<MaxMessageSize, SplitBuffers>>>::WithStorage(SplitBuffers, delegate, tracer, sesameInitializer)
         {}
     };
 }