Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

First draft of transport interfaces #337

Merged
merged 18 commits into from
Apr 5, 2024
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .clang-format
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,6 @@ BraceWrapping:
AfterStruct: true
AfterClass: true
AfterControlStatement: true
AfterEnum: true
AfterFunction: true
AfterUnion: true
AfterNamespace: true
Expand Down
28 changes: 19 additions & 9 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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]
Expand Down
22 changes: 22 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
pavel-kirienko marked this conversation as resolved.
Show resolved Hide resolved
```

### `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

Expand Down
3 changes: 2 additions & 1 deletion docs/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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)
pavel-kirienko marked this conversation as resolved.
Show resolved Hide resolved

list(APPEND DOXYGEN_INPUT_LIST ${ARG_INPUT_LIST})
list(JOIN DOXYGEN_INPUT_LIST "\\\n " DOXYGEN_INPUT )
Expand Down Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion docs/doxygen.ini
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/examples/example_01_hello_world.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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.
//
Expand Down
16 changes: 0 additions & 16 deletions include/libcyphal/libcyphal.hpp

This file was deleted.

38 changes: 38 additions & 0 deletions include/libcyphal/runnable.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
/// @file
/// libcyphal common header.
///
/// @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
{

/// @brief Declares an abstract Cyphal runnable interface.
///
/// Runnable objects do work asynchronously but only when `run()` is called.
/// This allows super-loop firmware to separate execution into application work and library work,
/// and for threaded software applications to service the library from dedicated threads.
/// Each object that implements `IRunnable` shall document how when it must be run to achieve certain functionality and
/// timing guarantees.
///
class IRunnable
{
public:
/// @brief Runs the runnable object.
virtual void run(TimePoint now) = 0;

protected:
virtual ~IRunnable() = default;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

rule of 5 is not upheld


}; // IRunnable

} // namespace libcyphal

#endif // LIBCYPHAL_RUNNABLE_HPP_INCLUDED
61 changes: 61 additions & 0 deletions include/libcyphal/transport/session/msg_sessions.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
/// @file
/// Defines the Message Session interfaces for Transport Layer implementations.
///
/// @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
{
inline namespace session
{

/// @brief Declares message RX session parameters.
///
struct MessageRxParams final
{
PortId subject_id;
std::size_t extent_bytes;

}; // MessageRxParams

/// @brief Declares message TX session parameters.
///
struct MessageTxParams final
{
PortId subject_id;

}; // MessageTxParams

/// @brief Declares an abstract Cyphal transport message RX session interface.
///
class IMessageRxSession : public IRunnable
{
public:
CETL_NODISCARD virtual MessageRxParams getParams() const noexcept = 0;
virtual void setTransferIdTimeout(Duration timeout) = 0;

}; // IMessageRxSession

/// @brief Declares an abstract Cyphal transport message TX session interface.
///
class IMessageTxSession : public IRunnable
{
public:
CETL_NODISCARD virtual MessageTxParams getParams() const noexcept = 0;

}; // IMessageTxSession

} // namespace session
} // namespace transport
} // namespace libcyphal

#endif // LIBCYPHAL_TRANSPORT_SESSION_MSG_SESSIONS_HPP_INCLUDED
32 changes: 32 additions & 0 deletions include/libcyphal/transport/session/session.hpp
pavel-kirienko marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
/// @file
/// Defines the Session interface for Transport Layer implementations.
///
/// @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"

namespace libcyphal
{
namespace transport
{
inline namespace session
{

/// @brief Declares an abstract Cyphal transport session interface.
///
class ISession : public IRunnable
{
public:
}; // ISession

} // namespace session
} // namespace transport
} // namespace libcyphal

#endif // LIBCYPHAL_TRANSPORT_SESSION_SESSION_HPP_INCLUDED
99 changes: 99 additions & 0 deletions include/libcyphal/transport/session/svc_sessions.hpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
/// @file
/// Defines the Service Session interfaces for Transport Layer implementations.
///
/// @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
{
inline namespace session
{

/// @brief Declares service request RX session parameters.
///
pavel-kirienko marked this conversation as resolved.
Show resolved Hide resolved
struct RequestRxParams final
{
PortId service_id;
std::size_t extent_bytes;

}; // RequestRxParams

/// @brief Declares service request TX session parameters.
///
struct RequestTxParams final
{
PortId service_id;
NodeId server_node_id;

}; // RequestTxParams

/// @brief Declares service response RX session parameters.
///
struct ResponseRxParams final
{
PortId service_id;
NodeId server_node_id;
std::size_t extent_bytes;

}; // ResponseRxParams

/// @brief Declares service response TX session parameters.
///
struct ResponseTxParams final
{
PortId service_id;

}; // ResponseTxParams

/// @brief Declares an abstract Cyphal transport request RX session interface.
///
class IRequestRxSession : public ISession
{
public:
CETL_NODISCARD virtual RequestRxParams getParams() const noexcept = 0;
virtual void setTransferIdTimeout(Duration timeout) = 0;
pavel-kirienko marked this conversation as resolved.
Show resolved Hide resolved

}; // IRequestRxSession

/// @brief Declares an abstract Cyphal transport request TX session interface.
///
class IRequestTxSession : public ISession
{
public:
CETL_NODISCARD virtual RequestTxParams getParams() const noexcept = 0;

}; // IRequestTxSession

/// @brief Declares an abstract Cyphal transport response RX session interface.
///
class IResponseRxSession : public ISession
{
public:
CETL_NODISCARD virtual ResponseRxParams getParams() const noexcept = 0;
virtual void setTransferIdTimeout(Duration timeout) = 0;
pavel-kirienko marked this conversation as resolved.
Show resolved Hide resolved

}; // IResponseRxSession

/// @brief Declares an abstract Cyphal transport response TX session interface.
///
class IResponseTxSession : public ISession
{
public:
CETL_NODISCARD virtual ResponseTxParams getParams() const noexcept = 0;

}; // IResponseTxSession

} // namespace session
} // namespace transport
} // namespace libcyphal

#endif // LIBCYPHAL_TRANSPORT_SESSION_SVC_SESSION_HPP_INCLUDED
Loading