Add thread yield capability

nandojve · nandojve · commit e9b2c0baa46c · 2025-06-27T18:45:25.000+02:00
Current the Behaviour Tree does not yield. This could lead to side
effects like starvation and lost of interrupts on critical systems.
This add the capability to the user define if engine should perform
a k_yield() to give opportunity to other threads with the same
priority to run.

This do not affect the time slice configuration and both can be
used. The time slice can be useful when a very long action may
block tree walk. To enable time slice make sure that behaviour
tree priority is greater than TIMESLICE_PRIORITY and
TIMESLICING=y.

The best walkthru performace can be achieve when
ZEPHYR_BEHAVIOUR_TREE_ALLOW_YIELD option is disabled.

Signed-off-by: Gerson Fernando Budke &lt;gerson.budke@ossystems.com.br&gt;
diff --git a/cmake/zephyrbt-from-behaviourtreecpp-xml.cmake b/cmake/zephyrbt-from-behaviourtreecpp-xml.cmake
@@ -1,16 +1,17 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 include(CheckIncludeFile)
 
 function(zephyrbt_define_from_behaviourtreecpp_xml
-    target      # The current target used to add the generated files
-    input_file  # The behaviour tree input file
-    output_inc  # Output directory of the generated header
-    output_src  # Output directory of the generated sources
-    stack_size  # The amount of RAM used to run the BT
-    thread_prio # The Thread Priority
+    target       # The current target used to add the generated files
+    input_file   # The behaviour tree input file
+    output_inc   # Output directory of the generated header
+    output_src   # Output directory of the generated sources
+    stack_size   # The amount of RAM used to run the BT
+    thread_prio  # The Thread Priority
+    thread_yield # The Thread yield option [ True or False ]
     )
   get_filename_component(zephyrbt_name ${input_file} NAME_WE [CACHE])
   get_filename_component(input_file ${input_file} ABSOLUTE)
@@ -31,6 +32,12 @@ function(zephyrbt_define_from_behaviourtreecpp_xml
     set(zephyrbt_user_include_file "")
   endif()
 
+  if(${thread_yield})
+    set(zephyrbt_thread_yield "-y True")
+  else()
+    set(zephyrbt_thread_yield "")
+  endif()
+
   add_custom_command(
     OUTPUT  ${zephyrbt_inc_file}
             ${zephyrbt_data_file}
@@ -44,6 +51,7 @@ function(zephyrbt_define_from_behaviourtreecpp_xml
       -ot ${zephyrbt_stub_file}
       -s  ${stack_size}
       -p  ${thread_prio}
+      ${zephyrbt_thread_yield}
       ${zephyrbt_user_include_file}
   )
 
diff --git a/include/zephyr/zephyrbt/zephyrbt.h b/include/zephyr/zephyrbt/zephyrbt.h
@@ -1,6 +1,6 @@
 /*
- * Copyright (c) 2024 O.S. Systems Software LTDA.
- * Copyright (c) 2024 Freedom Veiculos Eletricos
+ * Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+ * Copyright (c) 2024-2025 Freedom Veiculos Eletricos
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -89,6 +89,9 @@ struct zephyrbt_context {
 	const int stack_size;
 	const int thread_prio;
 	k_tid_t tid;
+#ifdef CONFIG_ZEPHYR_BEHAVIOUR_TREE_ALLOW_YIELD
+	bool thread_yield;
+#endif
 #endif
 };
 
@@ -102,10 +105,12 @@ struct zephyrbt_context {
  * @param _nodes	The Behaviour Tree nodes structure.
  * @param _stack_size	Thread stack size.
  * @param _thread_prio  Thread priority.
+ * @param _thread_yield Thread should yield. Default is True.
  * @param _user_data	User defined data. Default is NULL.
  * @param _blackboard	The Behaviour Tree blackboard structure.
  */
-#define ZEPHYRBT_DEFINE(_name, _nodes, _stack_size, _thread_prio, _user_data, _blackboard)	   \
+#define ZEPHYRBT_DEFINE(_name, _nodes, _stack_size, _thread_prio,				   \
+			_thread_yield, _user_data, _blackboard)					   \
 	STRUCT_SECTION_ITERABLE(zephyrbt_context, _name) = {					   \
 		IF_ENABLED(CONFIG_ZEPHYR_BEHAVIOUR_TREE_NODE_INFO, (				   \
 			.name = #_name,								   \
@@ -116,7 +121,10 @@ struct zephyrbt_context {
 		)										   \
 		IF_ENABLED(CONFIG_ZEPHYR_BEHAVIOUR_TREE_DYNAMIC, (				   \
 			.stack_size  = _stack_size,						   \
-			.thread_prio = _thread_prio, )						   \
+			.thread_prio = _thread_prio,						   \
+			IF_ENABLED(CONFIG_ZEPHYR_BEHAVIOUR_TREE_ALLOW_YIELD, (			   \
+				.thread_yield = _thread_yield, )				   \
+			))									   \
 		)										   \
 		.node       = _nodes,								   \
 		.nodes      = ARRAY_SIZE(_nodes),						   \
diff --git a/samples/subsys/zephyrbt/dynamic/CMakeLists.txt b/samples/subsys/zephyrbt/dynamic/CMakeLists.txt
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20.0)
@@ -23,6 +23,7 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
 
 zephyrbt_define_from_behaviourtreecpp_xml(app
@@ -31,4 +32,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
diff --git a/samples/subsys/zephyrbt/tutorial/CMakeLists.txt b/samples/subsys/zephyrbt/tutorial/CMakeLists.txt
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20.0)
@@ -23,4 +23,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
diff --git a/samples/subsys/zephyrbt/tutorial/lessons/lesson-1/resources/CMakeLists.txt b/samples/subsys/zephyrbt/tutorial/lessons/lesson-1/resources/CMakeLists.txt
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20.0)
@@ -24,4 +24,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
diff --git a/samples/subsys/zephyrbt/tutorial/lessons/lesson-2/resources/CMakeLists.txt b/samples/subsys/zephyrbt/tutorial/lessons/lesson-2/resources/CMakeLists.txt
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20.0)
@@ -24,4 +24,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
diff --git a/samples/subsys/zephyrbt/tutorial/lessons/lesson-3/resources/CMakeLists.txt b/samples/subsys/zephyrbt/tutorial/lessons/lesson-3/resources/CMakeLists.txt
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20.0)
@@ -25,4 +25,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
diff --git a/samples/subsys/zephyrbt/tutorial/lessons/lesson-4/resources/CMakeLists.txt b/samples/subsys/zephyrbt/tutorial/lessons/lesson-4/resources/CMakeLists.txt
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20.0)
@@ -26,4 +26,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
diff --git a/samples/subsys/zephyrbt/tutorial/lessons/lesson-5/resources/CMakeLists.txt b/samples/subsys/zephyrbt/tutorial/lessons/lesson-5/resources/CMakeLists.txt
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 cmake_minimum_required(VERSION 3.20.0)
@@ -27,4 +27,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app
 	${CMAKE_BINARY_DIR}/src
 	1024
 	0
+	yes
 )
diff --git a/scripts/generate-zephyrbt-from-behaviourtreecpp-xml b/scripts/generate-zephyrbt-from-behaviourtreecpp-xml
@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 """
@@ -214,7 +214,7 @@ def write_zephyrbt_blackboard_table(f, nodes, builtin, bt, blackboard, name):
 
 
 def generate_files(filename, output_inc, output_data, output_stub, builtin,
-                   nodes, bt, blackboard, stack, prio, user_file):
+                   nodes, bt, blackboard, stack, prio, thread_yield, user_file):
     with open(output_inc, "w") as f:
         f.write(HEADER)
         f.write(f"\n#ifndef {filename.upper()}_H")
@@ -235,7 +235,7 @@ def generate_files(filename, output_inc, output_data, output_stub, builtin,
         write_zephyrbt_nodes_table(f, nodes, builtin, bt, node_data_name)
         write_zephyrbt_blackboard_table(f, nodes, builtin, bt, blackboard, node_blackboard_name)
         f.write(f"\nZEPHYRBT_DEFINE({filename}, {filename}_nodes, ")
-        f.write(f"{stack}, {prio}, NULL, {filename}_blackboard);\n")
+        f.write(f"{stack}, {prio}, {'true' if thread_yield else 'false'}, NULL, {filename}_blackboard);\n")
 
     with open(output_stub, "w") as f:
         node_data_name = f"{filename}_nodes"
@@ -479,7 +479,7 @@ def clean_files(filename, dir):
 
 
 def main(zephyrbt_filename, output_inc, output_data, output_stub,
-         stack, prio, user_file) -> None:
+         stack, prio, thread_yield, user_file) -> None:
     zephyrbt = Path(zephyrbt_filename).stem
 
     sleep =    [['msec', 'input_port', None, 'Wait the amount of milliseconds']]
@@ -529,10 +529,11 @@ def main(zephyrbt_filename, output_inc, output_data, output_stub,
     print("-- Behaviour Tree: ", zephyrbt)
     print("-- Stack Size:     ", stack)
     print("-- Thread Priority:", prio)
+    print("-- Thread Yield:   ", thread_yield)
 
     nodes, bt, blackboard = build_bt_set(builtin, root)
     generate_files(zephyrbt, output_inc, output_data, output_stub, builtin,
-                   nodes, bt, blackboard, stack, prio, user_file)
+                   nodes, bt, blackboard, stack, prio, thread_yield, user_file)
 
 
 if __name__ == "__main__":
@@ -579,14 +580,22 @@ if __name__ == "__main__":
         default=0,
         help="The Thread Priority",
     )
+    parser.add_argument(
+        "-y",
+        "--thread_yield",
+        type=bool,
+        default=False,
+        help="The Thread yield",
+    )
     parser.add_argument(
         "-u",
         "--user_file",
         type=bool,
         default=False,
         help="Add user include file into code generation",
     )
+
     args = parser.parse_args()
 
     main(args.input, args.outinc, args.outdata, args.outstub,
-         args.stack, args.prio, args.user_file)
+         args.stack, args.prio, args.thread_yield, args.user_file)
diff --git a/subsys/zephyrbt/Kconfig b/subsys/zephyrbt/Kconfig
@@ -1,5 +1,5 @@
-# Copyright (c) 2024 O.S. Systems Software LTDA.
-# Copyright (c) 2024 Freedom Veiculos Eletricos
+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos
 # SPDX-License-Identifier: Apache-2.0
 
 config ZEPHYR_BEHAVIOUR_TREE
@@ -31,6 +31,25 @@ config ZEPHYR_BEHAVIOUR_TREE_DYNAMIC
 	help
 	  Enable use of dynamic memory.
 
+config ZEPHYR_BEHAVIOUR_TREE_ALLOW_YIELD
+	bool "Automatically yield on each turn"
+	depends on ZEPHYR_BEHAVIOUR_TREE_DYNAMIC
+	default y
+	help
+	  The behaviour tree will check to call k_yield() to give opportunity
+	  to same threads to execute. This do not affect the time slice
+	  configuration and both can be used.
+
+	  The time slice can be useful when a very long action may block tree
+	  walk. To enable time slice make sure that behaviour tree priority is
+	  greater than TIMESLICE_PRIORITY and TIMESLICING=y.
+
+	  If you want to have best walk performace you should disable this
+	  option. If you do that you can have side effects like starvation and
+	  may not attend all interrupts depending of the priority you select.
+
+	  If you do not know what you are configuring leave as is.
+
 config ZEPHYR_BEHAVIOUR_TREE_NODE_INIT
 	bool "Generate node initialization function"
 	depends on ZEPHYR_BEHAVIOUR_TREE_DYNAMIC
diff --git a/subsys/zephyrbt/zephyrbt.c b/subsys/zephyrbt/zephyrbt.c
@@ -1,6 +1,6 @@
 /*
- * Copyright (c) 2024 O.S. Systems Software LTDA.
- * Copyright (c) 2024 Freedom Veiculos Eletricos
+ * Copyright (c) 2024-2025 O.S. Systems Software LTDA.
+ * Copyright (c) 2024-2025 Freedom Veiculos Eletricos
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -130,6 +130,12 @@ void zephyrbt_thread_func(void *zephyrbt_ctx, void *, void *)
 	while (true) {
 		LOG_DBG("tick");
 		zephyrbt_evaluate(ctx, zephyrbt_get_root(ctx));
+
+#if defined(CONFIG_ZEPHYR_BEHAVIOUR_TREE_ALLOW_YIELD)
+		if (ctx->thread_yield) {
+			k_yield();
+		}
+#endif
 	}
 }
 

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`		`-# Copyright (c) 2024 O.S. Systems Software LTDA.`
`2`		`-# Copyright (c) 2024 Freedom Veiculos Eletricos`
	`1`	`+# Copyright (c) 2024-2025 O.S. Systems Software LTDA.`
	`2`	`+# Copyright (c) 2024-2025 Freedom Veiculos Eletricos`
`3`	`3`	`# SPDX-License-Identifier: Apache-2.0`
`4`	`4`
`5`	`5`	`cmake_minimum_required(VERSION 3.20.0)`
`@@ -23,6 +23,7 @@ zephyrbt_define_from_behaviourtreecpp_xml(app`
`23`	`23`	`${CMAKE_BINARY_DIR}/src`
`24`	`24`	`1024`
`25`	`25`	`0`
	`26`	`+ yes`
`26`	`27`	`)`
`27`	`28`
`28`	`29`	`zephyrbt_define_from_behaviourtreecpp_xml(app`
`@@ -31,4 +32,5 @@ zephyrbt_define_from_behaviourtreecpp_xml(app`
`31`	`32`	`${CMAKE_BINARY_DIR}/src`
`32`	`33`	`1024`
`33`	`34`	`0`
	`35`	`+ yes`
`34`	`36`	`)`