Skip to content

Commit 287dbfa

Browse files
abtinkabtink
authored
[test] introduce Nexus test framework and platform (openthread#10533)
This commit introduces a new test framework named Nexus. The framework includes the Nexus platform implementation that emulates platform behavior, allowing multiple nodes running the OpenThread core stack to be simulated and interact with each other within the same process. Unlike the simulation platform, where nodes run in separate processes and interact via POSIX sockets, Nexus nodes are simulated within a single process. Nexus tests can interact directly with the C++ or C OT core APIs, providing more control than the simulation platform's CLI-based interactions. The flow of time in Nexus tests is directly controlled by the test itself, allowing for quick time interval advancement. This model allows for faster and more scalable simulations, enabling quick simulation of larger networks for longer durations. This commit introduces the basic platform implementation, including: - `nexus_alarm`, `nexus_radio`, and `nexus_settings` modules. - Logging support, allowing logs to be distinguished per emulated node.
1 parent a79ca11 commit 287dbfa

23 files changed

+2152
-2
lines changed

‎.github/workflows/toranj.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,6 +190,30 @@ jobs:
190190
run: |
191191
./tests/toranj/build.sh posix-15.4
192192
193+
nexus:
194+
name: nexus
195+
runs-on: ubuntu-20.04
196+
steps:
197+
- name: Harden Runner
198+
uses: step-security/harden-runner@17d0e2bd7d51742c71671bd19fa12bdc9d40a3d6 # v2.8.1
199+
with:
200+
egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
201+
202+
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
203+
with:
204+
submodules: true
205+
- name: Bootstrap
206+
env:
207+
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
208+
run: |
209+
sudo apt-get update
210+
sudo apt-get --no-install-recommends install -y clang-10 clang++-10 ninja-build llvm lcov
211+
sudo apt-get --no-install-recommends install -y g++-multilib
212+
- name: Build & Run
213+
run: |
214+
./tests/nexus/build.sh
215+
ninja test
216+
193217
upload-coverage:
194218
needs:
195219
- toranj-cli

‎CMakeLists.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,11 @@ if(OT_PLATFORM STREQUAL "posix")
124124
add_subdirectory("${PROJECT_SOURCE_DIR}/src/posix/platform")
125125
elseif(OT_PLATFORM STREQUAL "external")
126126
# skip in this case
127+
elseif(OT_PLATFORM STREQUAL "nexus")
128+
if (OT_APP_CLI OR OT_APP_NCP OR OT_APP_RCP)
129+
message(FATAL_ERROR "no app (cli/ncp/rcp) should be enabled with nexus simulation platform")
130+
endif()
131+
target_compile_definitions(ot-config INTERFACE OPENTHREAD_PLATFORM_NEXUS=1)
127132
else()
128133
target_include_directories(ot-config INTERFACE ${PROJECT_SOURCE_DIR}/examples/platforms/${OT_PLATFORM})
129134
add_subdirectory("${PROJECT_SOURCE_DIR}/examples/platforms/${OT_PLATFORM}")

‎etc/cmake/options.cmake‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -265,7 +265,7 @@ message(STATUS "- - - - - - - - - - - - - - - - ")
265265
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
266266
# Get a list of the available platforms and output as a list to the 'arg_platforms' argument
267267
function(ot_get_platforms arg_platforms)
268-
list(APPEND result "NO" "posix" "external")
268+
list(APPEND result "NO" "posix" "external" "nexus")
269269
set(platforms_dir "${PROJECT_SOURCE_DIR}/examples/platforms")
270270
file(GLOB platforms RELATIVE "${platforms_dir}" "${platforms_dir}/*")
271271
foreach(platform IN LISTS platforms)

‎src/core/instance/instance.hpp‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,15 @@ class Instance : public otInstance, private NonCopyable
252252
*/
253253
uint32_t GetId(void) const { return mId; }
254254

255+
#if OPENTHREAD_PLATFORM_NEXUS
256+
/**
257+
* Sets the instance identifier.
258+
*
259+
* @param[in] aId The identifier to assign to the `Instance`.
260+
*/
261+
void SetId(uint32_t aId) { mId = aId; }
262+
#endif
263+
255264
/**
256265
* Indicates whether or not the instance is valid/initialized and not yet finalized.
257266
*
@@ -412,9 +421,23 @@ class Instance : public otInstance, private NonCopyable
412421
*/
413422
template <typename Type> inline Type &Get(void);
414423

424+
#if OPENTHREAD_PLATFORM_NEXUS
425+
/**
426+
* Constructor to initialize an `Instance`
427+
*/
428+
Instance(void);
429+
430+
/**
431+
* Called after constructor initialization.
432+
*/
433+
void AfterInit(void);
434+
#endif
435+
415436
private:
437+
#if !OPENTHREAD_PLATFORM_NEXUS
416438
Instance(void);
417439
void AfterInit(void);
440+
#endif
418441

419442
// Order of variables (their initialization in `Instance`)
420443
// is important.

‎tests/CMakeLists.txt‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828

2929
option(OT_BUILD_GTEST "enable gtest")
3030

31-
if(OT_FTD AND BUILD_TESTING)
31+
if(OT_FTD AND BUILD_TESTING AND (NOT OT_PLATFORM STREQUAL "nexus"))
3232
add_subdirectory(unit)
3333
if(OT_BUILD_GTEST)
3434
add_subdirectory(gtest)
@@ -40,3 +40,7 @@ option(OT_FUZZ_TARGETS "enable fuzz targets" OFF)
4040
if(OT_FUZZ_TARGETS)
4141
add_subdirectory(fuzz)
4242
endif()
43+
44+
if(OT_PLATFORM STREQUAL "nexus")
45+
add_subdirectory(nexus)
46+
endif()

‎tests/nexus/CMakeLists.txt‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
#
2+
# Copyright (c) 2024, The OpenThread Authors.
3+
# All rights reserved.
4+
#
5+
# Redistribution and use in source and binary forms, with or without
6+
# modification, are permitted provided that the following conditions are met:
7+
# 1. Redistributions of source code must retain the above copyright
8+
# notice, this list of conditions and the following disclaimer.
9+
# 2. Redistributions in binary form must reproduce the above copyright
10+
# notice, this list of conditions and the following disclaimer in the
11+
# documentation and/or other materials provided with the distribution.
12+
# 3. Neither the name of the copyright holder nor the
13+
# names of its contributors may be used to endorse or promote products
14+
# derived from this software without specific prior written permission.
15+
#
16+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
20+
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
# POSSIBILITY OF SUCH DAMAGE.
27+
#
28+
29+
set(COMMON_INCLUDES
30+
${PROJECT_SOURCE_DIR}/include
31+
${PROJECT_SOURCE_DIR}/src
32+
${PROJECT_SOURCE_DIR}/src/core
33+
${PROJECT_SOURCE_DIR}/tests/nexus/platform
34+
)
35+
36+
set(COMMON_COMPILE_OPTIONS
37+
-DOPENTHREAD_FTD=1
38+
-DOPENTHREAD_MTD=0
39+
-DOPENTHREAD_RADIO=0
40+
)
41+
42+
add_library(ot-nexus-platform
43+
platform/nexus_alarm.cpp
44+
platform/nexus_core.cpp
45+
platform/nexus_misc.cpp
46+
platform/nexus_node.cpp
47+
platform/nexus_radio.cpp
48+
platform/nexus_settings.cpp
49+
)
50+
51+
target_include_directories(ot-nexus-platform
52+
PRIVATE
53+
${COMMON_INCLUDES}
54+
)
55+
56+
target_compile_options(ot-nexus-platform
57+
PRIVATE
58+
${COMMON_COMPILE_OPTIONS}
59+
)
60+
61+
target_link_libraries(ot-nexus-platform
62+
PRIVATE
63+
ot-config
64+
${OT_MBEDTLS}
65+
)
66+
67+
set(COMMON_LIBS
68+
ot-nexus-platform
69+
openthread-ftd
70+
ot-nexus-platform
71+
${OT_MBEDTLS}
72+
ot-config
73+
openthread-ftd
74+
)
75+
76+
#----------------------------------------------------------------------------------------------------------------------
77+
78+
macro(ot_nexus_test name)
79+
80+
# Macro to add an OpenThread nexus test.
81+
#
82+
# Nexus test name will be `nexus_{name}`. Test source file of
83+
# `test_{name}.cpp` is used. Optional extra arguments can be
84+
# passed to provide additional source files.
85+
86+
add_executable(nexus_${name}
87+
test_${name}.cpp ${ARGN}
88+
)
89+
90+
target_include_directories(nexus_${name}
91+
PRIVATE
92+
${COMMON_INCLUDES}
93+
)
94+
95+
target_link_libraries(nexus_${name}
96+
PRIVATE
97+
${COMMON_LIBS}
98+
)
99+
100+
target_compile_options(nexus_${name}
101+
PRIVATE
102+
${COMMON_COMPILE_OPTIONS}
103+
)
104+
105+
add_test(NAME nexus_${name} COMMAND nexus_${name})
106+
endmacro()
107+
108+
109+
#----------------------------------------------------------------------------------------------------------------------
110+
111+
ot_nexus_test(form_join)
112+
ot_nexus_test(large_network)

‎tests/nexus/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Nexus test framework
2+
3+
Nexus is a test framework for OpenThread testing.
4+
5+
### Design Goals
6+
7+
- **Faster and more scalable network simulation**: Enable faster and more efficient simulations of OpenThread networks involving a large number of nodes over extended durations.
8+
- **Enhanced control**: Achieve greater control and scalability over simulated tests.
9+
10+
### Features
11+
12+
- Includes the Nexus platform implementation that emulates platform behavior, allowing multiple nodes running the OpenThread core stack to be simulated and interact with each other within the same process.
13+
- Unlike the simulation platform (under `examples/platforms/simulation`), where nodes run in separate processes and interact via POSIX sockets, Nexus nodes are simulated within a single process.
14+
- Nexus tests can interact directly with the C++ or C OT core APIs, providing more control than the simulation platform's CLI-based interactions.
15+
- The flow of time in Nexus tests is directly controlled by the test itself, allowing for quick time interval advancement.
16+
17+
### How to build and run tests
18+
19+
To build Nexus test cases, the `build.sh` script can be used:
20+
21+
```bash
22+
./tests/nexus/build.sh
23+
```
24+
25+
Afterwards, each test can be run directly:
26+
27+
```bash
28+
./tests/nexus/nexus_form_join
29+
```

‎tests/nexus/build.sh‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
#!/bin/bash
2+
#
3+
# Copyright (c) 2024, The OpenThread Authors.
4+
# All rights reserved.
5+
#
6+
# Redistribution and use in source and binary forms, with or without
7+
# modification, are permitted provided that the following conditions are met:
8+
# 1. Redistributions of source code must retain the above copyright
9+
# notice, this list of conditions and the following disclaimer.
10+
# 2. Redistributions in binary form must reproduce the above copyright
11+
# notice, this list of conditions and the following disclaimer in the
12+
# documentation and/or other materials provided with the distribution.
13+
# 3. Neither the name of the copyright holder nor the
14+
# names of its contributors may be used to endorse or promote products
15+
# derived from this software without specific prior written permission.
16+
#
17+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19+
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20+
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
21+
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22+
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23+
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24+
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25+
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26+
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27+
# POSSIBILITY OF SUCH DAMAGE.
28+
#
29+
30+
display_usage()
31+
{
32+
echo ""
33+
echo "Nexus build script "
34+
echo ""
35+
echo ""
36+
}
37+
38+
die()
39+
{
40+
echo " *** ERROR: " "$*"
41+
exit 1
42+
}
43+
44+
cd "$(dirname "$0")" || die "cd failed"
45+
cd ../.. || die "cd failed"
46+
47+
if [ -n "${top_builddir}" ]; then
48+
top_srcdir=$(pwd)
49+
mkdir -p "${top_builddir}"
50+
else
51+
top_srcdir=.
52+
top_builddir=.
53+
fi
54+
55+
echo "===================================================================================================="
56+
echo "Building OpenThread Nexus test platform"
57+
echo "===================================================================================================="
58+
cd "${top_builddir}" || die "cd failed"
59+
cmake -GNinja -DOT_PLATFORM=nexus -DOT_COMPILE_WARNING_AS_ERROR=ON \
60+
-DOT_MULTIPLE_INSTANCE=ON \
61+
-DOT_THREAD_VERSION=1.4 -DOT_APP_CLI=OFF -DOT_APP_NCP=OFF -DOT_APP_RCP=OFF \
62+
-DOT_PROJECT_CONFIG=../tests/nexus/openthread-core-nexus-config.h \
63+
"${top_srcdir}" || die
64+
ninja || die
65+
66+
exit 0

0 commit comments

Comments
 (0)