First draft of transport interfaces

.clang-format

@@ -28,7 +28,6 @@ BraceWrapping:
     AfterStruct: true
     AfterClass: true
     AfterControlStatement: true
-    AfterEnum: true
     AfterFunction: true
     AfterUnion: true
     AfterNamespace: true

.github/workflows/tests.yml

@@ -1,18 +1,11 @@
 name: "libcyphal_test"
 
 on:
-  push:
-    branches:
-      - main
-      - 'issue/*'
-      # todo: temp - remove this later!
-      - 'sshirokov/CI_*'
+  push:  # Further filtering is done in the jobs.
   pull_request:
     branches:
       - main
       - 'issue/*'
-      # todo: temp - remove this later!
-      - 'sshirokov/CI_*'
 
 # To test use https://github.com/nektos/act and specify the event as "act"
 # For example:
@@ -24,6 +17,12 @@ on:
 # before running act).
 jobs:
   warmup:
+    if: >
+      contains(github.event.head_commit.message, '#verification') ||
+      contains(github.event.head_commit.message, '#docs') ||
+      contains(github.ref, '/main') ||
+      contains(github.ref, '/issue/') ||
+      (github.event_name == 'pull_request')
     runs-on: ubuntu-latest
     container: ghcr.io/opencyphal/toolshed:ts22.4.3
     steps:
@@ -52,12 +51,18 @@ jobs:
           --build-flavor Debug
           clean-configure
   verification:
+    if: >
+      contains(github.event.head_commit.message, '#verification') ||
+      contains(github.ref, '/main') ||
+      contains(github.ref, '/issue/') ||
+      (github.event_name == 'pull_request')
     runs-on: ubuntu-latest
     container: ghcr.io/opencyphal/toolshed:ts22.4.3
     needs: [warmup]
     strategy:
       matrix:
         flavor: [Release, Debug]
+        std: [14, 17, 20]
         toolchain: [gcc, clang]
     steps:
     - uses: actions/checkout@v4
@@ -79,11 +84,16 @@ jobs:
         ./build-tools/bin/verify.py
         --verbose
         --asserts
-        --cpp-standard 14
+        --cpp-standard ${{ matrix.std }}
         --build-flavor ${{ matrix.flavor }}
         --toolchain ${{ matrix.toolchain }}
         clean-release
   docs:
+    if: >
+      contains(github.event.head_commit.message, '#docs') ||
+      contains(github.ref, '/main') ||
+      contains(github.ref, '/issue/') ||
+      (github.event_name == 'pull_request')
     runs-on: ubuntu-latest
     container: ghcr.io/opencyphal/toolshed:ts22.4.3
     needs: [warmup]

CONTRIBUTING.md

@@ -193,6 +193,28 @@ Reviewers, please check the following items when reviewing a pull-request:
     * Are the tests maintainable?
     * Is the code in the right namespace/class/function?
 
+### Format the sources
+
+Clang-Format may format the sources differently depending on the version used.
+To ensure that the formatting matches the expectations of the CI suite,
+invoke Clang-Format of the correct version from the container (be sure to use the correct image tag):
+
+```
+docker run --rm -v ${PWD}:/repo ghcr.io/opencyphal/toolshed:ts22.4.3 ./build-tools/bin/verify.py build-danger-danger-repo-clang-format-in-place
+```
+
+### `issue/*` and hashtag-based CI triggering
+
+Normally, the CI will only run on pull requests (PR), releases, and perhaps some other special occasions on `main` branch.
+Often, however, you will want to run it on your branch before proposing the changes to ensure all checks are
+green and test coverage is adequate - to do that:
+- either target your PR to any `issue/NN_LABEL` branch, where `NN` is the issue number and `LABEL` is a small title giving context (like `issue/83_any`)
+- or add a hashtag with the name of the workflow you need to run to the head commit;
+for example, making a commit with a message like `Add feature such and such #verification #docs #sonar`
+will force the CI to execute jobs named `verification`, `docs`, and `sonar`.
+
+Note that if the job you requested is dependent on other jobs that are not triggered, it will not run; 
+for example, if `sonar` requires `docs`, pushing a commit with `#sonar` alone will not make it run.
 
 ## CAN bus Physical Layer Notes
 

docs/CMakeLists.txt

@@ -64,6 +64,7 @@ function (create_docs_target ARG_DOCS_DOXY_ROOT
     set(DOXYGEN_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})
     set(DOXYGEN_CONFIG_FILE ${DOXYGEN_OUTPUT_DIRECTORY}/doxygen.config)
     set(DOXYGEN_EXAMPLE_PATH ${ARG_EXAMPLES_PATH})
+    set(DOXYGEN_STRIP_FROM_PATH ${ARG_DOCS_DOXY_ROOT}/../include/libcyphal)
 
     list(APPEND DOXYGEN_INPUT_LIST ${ARG_INPUT_LIST})
     list(JOIN DOXYGEN_INPUT_LIST "\\\n    " DOXYGEN_INPUT )
@@ -129,7 +130,7 @@ endfunction(create_docs_target)
 file(GLOB_RECURSE DOXYGEN_INPUT_LIST
     LIST_DIRECTORIES false
     CONFIGURE_DEPENDS
-    ${LIBCYPHAL_ROOT}/include/libcyphal/**/*.hpp
+    ${LIBCYPHAL_ROOT}/include/**/*.hpp
 )
 
 get_property(LOCAL_EXAMPLES DIRECTORY "examples" PROPERTY IN_BUILD_TESTS)

docs/doxygen.ini

@@ -184,7 +184,7 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        =
+STRIP_FROM_PATH        = @DOXYGEN_STRIP_FROM_PATH@
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which

docs/examples/example_01_hello_world.cpp

@@ -7,7 +7,7 @@
 /// SPDX-License-Identifier: MIT
 ///
 
-#include "libcyphal/libcyphal.hpp"
+#include "libcyphal/types.hpp"
 
 // TODO: Uncomment this when we have a real example to test.
 //

include/libcyphal/runnable.hpp

@@ -0,0 +1,25 @@
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+
+#ifndef LIBCYPHAL_RUNNABLE_HPP_INCLUDED
+#define LIBCYPHAL_RUNNABLE_HPP_INCLUDED
+
+#include "types.hpp"
+
+namespace libcyphal
+{
+
+class IRunnable
+{
+public:
+    virtual void run(const TimePoint now) = 0;
+
+protected:
+    virtual ~IRunnable() = default;
+};
+
+}  // namespace libcyphal
+
+#endif  // LIBCYPHAL_RUNNABLE_HPP_INCLUDED

include/libcyphal/transport/defines.hpp

@@ -0,0 +1,40 @@
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+
+#ifndef LIBCYPHAL_TRANSPORT_DEFINES_HPP_INCLUDED
+#define LIBCYPHAL_TRANSPORT_DEFINES_HPP_INCLUDED
+
+namespace libcyphal
+{
+namespace transport
+{
+
+/// @brief `NodeId` is a 16-bit unsigned integer that represents a node in a Cyphal network.
+///
+/// Anonymity is represented by an empty `cetl::optional<NodeId>` (see `cetl::nullopt`).
+///
+using NodeId = std::uint16_t;
+
+/// @brief `PortId` is a 16-bit unsigned integer that represents a port (subject & service) in a Cyphal network.
+///
+using PortId = std::uint16_t;
+
+/// @brief `TransferId` is a 64-bit unsigned integer that represents a service transfer (request & response)
+/// in a Cyphal network.
+///
+using TransferId = std::uint64_t;
+
+struct ProtocolParams final
+{
+    NodeId        max_nodes;
+    std::size_t   mtu_bytes;
+    std::uint64_t transfer_id_modulo;
+
+};  // ProtocolParams
+
+}  // namespace transport
+}  // namespace libcyphal
+
+#endif  // LIBCYPHAL_TRANSPORT_DEFINES_HPP_INCLUDED

include/libcyphal/transport/session/msg_sessions.hpp

@@ -0,0 +1,45 @@
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+
+#ifndef LIBCYPHAL_TRANSPORT_SESSION_MSG_SESSIONS_HPP_INCLUDED
+#define LIBCYPHAL_TRANSPORT_SESSION_MSG_SESSIONS_HPP_INCLUDED
+
+#include "session.hpp"
+
+namespace libcyphal
+{
+namespace transport
+{
+namespace session
+{
+
+struct MessageRxParams final
+{
+    std::size_t extent_bytes;
+    PortId      subject_id;
+};
+
+struct MessageTxParams final
+{
+    PortId subject_id;
+};
+
+class IMessageRxSession : public IRxSession
+{
+public:
+    CETL_NODISCARD virtual MessageRxParams getParams() const noexcept = 0;
+};
+
+class IMessageTxSession : public IRunnable
+{
+public:
+    CETL_NODISCARD virtual MessageTxParams getParams() const noexcept = 0;
+};
+
+}  // namespace session
+}  // namespace transport
+}  // namespace libcyphal
+
+#endif  // LIBCYPHAL_TRANSPORT_SESSION_MSG_SESSIONS_HPP_INCLUDED

include/libcyphal/transport/session/session.hpp

@@ -0,0 +1,34 @@
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+
+#ifndef LIBCYPHAL_TRANSPORT_SESSION_SESSION_HPP_INCLUDED
+#define LIBCYPHAL_TRANSPORT_SESSION_SESSION_HPP_INCLUDED
+
+#include "libcyphal/runnable.hpp"
+#include "libcyphal/transport/defines.hpp"
+
+namespace libcyphal
+{
+namespace transport
+{
+namespace session
+{
+
+class ISession : public IRunnable
+{
+public:
+};
+
+class IRxSession : public ISession
+{
+public:
+    virtual void setTransferIdTimeout(const Duration timeout) = 0;
+};
+
+}  // namespace session
+}  // namespace transport
+}  // namespace libcyphal
+
+#endif  // LIBCYPHAL_TRANSPORT_SESSION_SESSION_HPP_INCLUDED

include/libcyphal/transport/session/svc_sessions.hpp

@@ -0,0 +1,70 @@
+/// @copyright
+/// Copyright (C) OpenCyphal Development Team  <opencyphal.org>
+/// Copyright Amazon.com Inc. or its affiliates.
+/// SPDX-License-Identifier: MIT
+
+#ifndef LIBCYPHAL_TRANSPORT_SESSION_SVC_SESSION_HPP_INCLUDED
+#define LIBCYPHAL_TRANSPORT_SESSION_SVC_SESSION_HPP_INCLUDED
+
+#include "session.hpp"
+
+namespace libcyphal
+{
+namespace transport
+{
+namespace session
+{
+
+struct RequestRxParams final
+{
+    std::size_t extent_bytes;
+    PortId      service_id;
+};
+
+struct RequestTxParams final
+{
+    PortId service_id;
+    NodeId server_node_id;
+};
+
+struct ResponseRxParams final
+{
+    std::size_t extent_bytes;
+    PortId      service_id;
+    NodeId      server_node_id;
+};
+
+struct ResponseTxParams final
+{
+    PortId service_id;
+};
+
+class IRequestRxSession : public IRxSession
+{
+public:
+    CETL_NODISCARD virtual RequestRxParams getParams() const noexcept = 0;
+};
+
+class IRequestTxSession : public ISession
+{
+public:
+    CETL_NODISCARD virtual RequestTxParams getParams() const noexcept = 0;
+};
+
+class IResponseRxSession : public IRxSession
+{
+public:
+    CETL_NODISCARD virtual ResponseRxParams getParams() const noexcept = 0;
+};
+
+class IResponseTxSession : public ISession
+{
+public:
+    CETL_NODISCARD virtual ResponseTxParams getParams() const noexcept = 0;
+};
+
+}  // namespace session
+}  // namespace transport
+}  // namespace libcyphal
+
+#endif  // LIBCYPHAL_TRANSPORT_SESSION_SVC_SESSION_HPP_INCLUDED