fff: Add fff_extensions.h, RETURN_HANDLED_CONTEXT()

Add supplementary header <zephyr/fff_extensions.h>.  Add macro
to fff_extensions.h for simplifying definition of custom fake functions
needing call-unique information for producing desired output data.
When an array of custom fake context structures is defined and
the return field within the first structure instance is registered
with the standard SET_RETURN_SEQ() macro of FFF, the
RETURN_HANDLED_CONTEXT() macro provides the inverse logic to
recover the context structure for this called instance. The body of
the custom fake handler is provided to the RETURN_HANDLED_CONTEXT()
macro for appropriate execution and access to the custom fake
parameters.

A test suite is also provided to verify macro implementation and
illustrate usage. It is at:
zephyr/tests/subsys/testsuite/fff_fake_contexts/

This code was verified by:

1. (Pass) west build -p always \
            -b unit_testing tests/subsys/testsuite/fff_fake_contexts/ && \
         ./build/testbinary
2. (Pass) west build -p always \
            -b native_posix tests/subsys/testsuite/fff_fake_contexts/ && \
         ./build/zephyr/zephyr.exe
3. (Pass) ./scripts/twister -p unit_testing \
            -T tests/subsys/testsuite/fff_fake_contexts/
4. (Pass) ./scripts/twister -p native_posix \
            -T tests/subsys/testsuite/fff_fake_contexts/
5. (Pass) cd doc && build html-fast

Fix #55246

Signed-off-by: Gregory Shue <[email protected]>

Author: legrand-gregshue

doc/develop/test/ztest.rst

@@ -520,13 +520,14 @@ Example output for a failed macro from
 .. doxygengroup:: ztest_assume
 
 
-.. _mocking-fff:
-
 Ztress
 ======
 
 .. doxygengroup:: ztest_ztress
 
+
+.. _mocking-fff:
+
 Mocking via FFF
 ===============
 
@@ -544,6 +545,9 @@ devicetree bindings for more information:
  - :dtcompatible:`zephyr,fake-can`
  - :dtcompatible:`zephyr,fake-eeprom`
 
+Zephyr also has defined extensions to FFF for simplified declarations of fake functions.
+See :ref:`FFF Extensions <fff-extensions>`.
+
 Customizing Test Output
 ***********************
 The way output is presented when running tests can be customized.
@@ -594,4 +598,13 @@ For example
     $ zephyr.exe -test="fixture_tests::test_fixture_pointer,framework_tests::test_assert_mem_equal"
     $ zephyr.exe -test="framework_tests::*"
 
+
+.. _fff-extensions:
+
+FFF Extensions
+**************
+
+.. doxygengroup:: fff_extensions
+
+
 .. _FFF: https://github.com/meekrosoft/fff

doc/zephyr.doxyfile.in

@@ -925,6 +925,7 @@ INPUT                  = @ZEPHYR_BASE@/doc/_doxygen/mainpage.md \
                          @ZEPHYR_BASE@/kernel/include/kernel_arch_interface.h \
                          @ZEPHYR_BASE@/include/ \
                          @ZEPHYR_BASE@/lib/libc/minimal/include/ \
+                         @ZEPHYR_BASE@/subsys/testsuite/include/ \
                          @ZEPHYR_BASE@/subsys/testsuite/ztest/include/ \
                          @ZEPHYR_BASE@/tests/kernel/
 

subsys/testsuite/include/zephyr/fff_extensions.h

@@ -0,0 +1,98 @@
+/*
+ * Copyright(c) 2023 Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ *
+ * @brief Zephyr testing framework FFF extension macros
+ */
+
+#ifndef ZEPHYR_SUBSYS_TESTSUITE_INCLUDE_ZEPHYR_FFF_EXTENSIONS_H_
+#define ZEPHYR_SUBSYS_TESTSUITE_INCLUDE_ZEPHYR_FFF_EXTENSIONS_H_
+
+#include <zephyr/fff.h>
+#include <zephyr/sys/util.h> /* for CONTAINER_OF */
+
+/**
+ * @defgroup fff_extensions FFF extensions
+ * @ingroup all_tests
+ *
+ * This module provides extensions to FFF for simplifying the
+ * configuration and usage of fakes.
+ *
+ * @{
+ */
+
+
+/**
+ * @brief Wrap custom fake body to extract defined context struct
+ *
+ * Add extension macro for simplified creation of
+ * fake functions needing call-specific context data.
+ *
+ * This macro enables a fake to be implemented as follows and
+ * requires no familiarity with the inner workings of FFF.
+ *
+ * @code
+ * struct FUNCNAME##_custom_fake_context
+ * {
+ *     struct instance * const instance;
+ *     int result;
+ * };
+ *
+ * int FUNCNAME##_custom_fake(
+ *     const struct instance **instance_out)
+ * {
+ *     RETURN_HANDLED_CONTEXT(
+ *         FUNCNAME,
+ *         struct FUNCNAME##_custom_fake_context,
+ *         result,
+ *         context,
+ *         {
+ *             if (context != NULL)
+ *             {
+ *                 if (context->result == 0)
+ *                 {
+ *                     if (instance_out != NULL)
+ *                     {
+ *                         *instance_out = context->instance;
+ *                     }
+ *                 }
+ *                 return context->result;
+ *             }
+ *             return FUNCNAME##_fake.return_val;
+ *         }
+ *     );
+ * }
+ * @endcode
+ *
+ * @param FUNCNAME Name of function being faked
+ * @param CONTEXTTYPE type of custom defined fake context struct
+ * @param RESULTFIELD name of field holding the return type & value
+ * @param CONTEXTPTRNAME expected name of pointer to custom defined fake context struct
+ * @param HANDLERBODY in-line custom fake handling logic
+ */
+
+#define RETURN_HANDLED_CONTEXT(FUNCNAME,                                      \
+		CONTEXTTYPE, RESULTFIELD, CONTEXTPTRNAME, HANDLERBODY)        \
+	if (FUNCNAME##_fake.return_val_seq_len) {                             \
+		CONTEXTTYPE * const contexts =                                \
+		CONTAINER_OF(FUNCNAME##_fake.return_val_seq,                  \
+				CONTEXTTYPE, RESULTFIELD);                    \
+		size_t const seq_idx = (FUNCNAME##_fake.return_val_seq_idx <  \
+					FUNCNAME##_fake.return_val_seq_len) ? \
+					FUNCNAME##_fake.return_val_seq_idx++ :\
+					FUNCNAME##_fake.return_val_seq_idx - 1;\
+		CONTEXTTYPE * const CONTEXTPTRNAME = &contexts[seq_idx];      \
+		HANDLERBODY;                                                  \
+	}                                                                     \
+	return FUNCNAME##_fake.return_val
+
+/**
+ * @}
+ */
+
+#endif /* ZEPHYR_SUBSYS_TESTSUITE_INCLUDE_ZEPHYR_FFF_EXTENSIONS_H_ */

tests/subsys/testsuite/fff_fake_contexts/CMakeLists.txt

@@ -0,0 +1,23 @@
+# Copyright (c) 2023 Legrand North America, LLC.
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+if(BOARD STREQUAL unit_testing)
+  find_package(Zephyr COMPONENTS unittest REQUIRED HINTS $ENV{ZEPHYR_BASE})
+  set(target testbinary)
+else()
+  find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+  set(target app)
+endif()
+
+project(base)
+target_sources(${target} PRIVATE
+  src/code_under_test.c
+  src/main.c
+  src/fakes/called_API.c
+)
+
+target_include_directories(${target} PRIVATE
+  ${CMAKE_CURRENT_SOURCE_DIR}/src
+  ${CMAKE_CURRENT_SOURCE_DIR}/include
+)

tests/subsys/testsuite/fff_fake_contexts/include/zephyr/called_API.h

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2023 Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_INCLUDE_ZEPHYR_CALLED_API_H_
+#define ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_INCLUDE_ZEPHYR_CALLED_API_H_
+
+#include <errno.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* A container struct for hidden instance data */
+struct called_API_info;
+
+/**
+ * @brief Provide an instance handle to a session of the called_API.
+ *
+ * This API is defined for the code_under_test() example to call.
+ * It represents a routine which provides call-unique data to the caller
+ * as well as providing a return value.  This requires the _custom_fake
+ * implementation to serve the data from a custom_fake context struture,
+ * where each call needs to return a unique, configured value.
+ *
+ * @param instance_out Session instance handle for caller to use.
+ *
+ * @return zero(0) upon success, with *instance_out updated.
+ * @return -EINVAL if invalid parameter(s)
+ * @return -E2BIG  if more calls were made than expected.
+ */
+int called_API_open(const struct called_API_info **instance_out);
+
+/**
+ * @brief Return an instance handle to a session of the called_API.
+ *
+ * This API is defined for the code_under_test() example to call.
+ * It represents a routine which requires specific data from the caller
+ * as well as providing a return value.  This is defined to
+ * have the code_under_test call multiple functions to illustrate
+ * a way to verify a specific calling sequence was made
+ *
+ * @param instance Session instance handle provided by called_API_open
+ *
+ * @return zero(0) upon success, with instance invalidated.
+ * @return -EINVAL if invalid parameter(s)
+ * @return -E2BIG  if more calls were made than expected.
+ */
+int called_API_close(const struct called_API_info *instance);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_INCLUDE_ZEPHYR_CALLED_API_H_ */

tests/subsys/testsuite/fff_fake_contexts/include/zephyr/code_under_test.h

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2023 Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_INCLUDE_ZEPHYR_CODE_UNDER_TEST_H_
+#define ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_INCLUDE_ZEPHYR_CODE_UNDER_TEST_H_
+
+#include <errno.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Opens and closes called_API session twice
+ *
+ * This routine loops twice on opening/closing a called_API session.
+ * Failures cause early termination of the loop, and the error number
+ * from the called routine is returned by this routine.  This routine
+ * is designed for exercising custom_fake routines that need to use
+ * call-specific data.
+ *
+ * @return zero(0) upon success
+ * @return -EINVAL if invalid parameter(s)
+ * @return -E2BIG  if more calls were made than expected.
+ */
+int code_under_test(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_INCLUDE_ZEPHYR_CODE_UNDER_TEST_H_ */

tests/subsys/testsuite/fff_fake_contexts/prj.conf

@@ -0,0 +1,5 @@
+# Copyright (c) 2023 Legrand North America, LLC.
+# SPDX-License-Identifier: Apache-2.0
+
+CONFIG_ZTEST=y
+CONFIG_ZTEST_NEW_API=y

tests/subsys/testsuite/fff_fake_contexts/src/code_under_test.c

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) 2023 Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stdio.h> /* NULL */
+#include <zephyr/called_API.h>
+#include <zephyr/code_under_test.h>
+
+
+int code_under_test(void)
+{
+	int result = 0;
+
+	for (int i = 0; i < 2; ++i) {
+		const struct called_API_info *called_API = NULL;
+
+		result = called_API_open(&called_API);
+		if (result != 0) {
+			break;
+		}
+
+		result = called_API_close(called_API);
+		if (result != 0) {
+			break;
+		}
+
+	}
+
+	return result;
+}

tests/subsys/testsuite/fff_fake_contexts/src/fakes/called_API.c

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2023 Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/fff.h>
+
+#include "fakes/called_API.h"
+
+DEFINE_FAKE_VALUE_FUNC(int, called_API_open, const struct called_API_info **);
+DEFINE_FAKE_VALUE_FUNC(int, called_API_close, const struct called_API_info *);

tests/subsys/testsuite/fff_fake_contexts/src/fakes/called_API.h

@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2023 Legrand North America, LLC.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_FAKES_CALLED_API_H_
+#define ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_FAKES_CALLED_API_H_
+
+#include <zephyr/fff.h>
+#include <zephyr/called_API.h>
+
+#define ZEPHYR_CALLED_API_FFF_FAKES_LIST(FAKE) \
+		FAKE(called_API_open)	\
+		FAKE(called_API_close)	\
+
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+DECLARE_FAKE_VALUE_FUNC(int, called_API_open, const struct called_API_info **);
+DECLARE_FAKE_VALUE_FUNC(int, called_API_close, const struct called_API_info *);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_TESTS_SUBSYS_TESTSUITE_FFF_FAKE_CONTEXTS_FAKES_CALLED_API_H_ */