vsf_test.h

Go to the documentation of this file.

/*****************************************************************************
 *   Copyright(C)2009-2024 by VSF Team                                       *
 *                                                                           *
 *  Licensed under the Apache License, Version 2.0 (the "License");          *
 *  you may not use this file except in compliance with the License.         *
 *  You may obtain a copy of the License at                                  *
 *                                                                           *
 *     http://www.apache.org/licenses/LICENSE-2.0                            *
 *                                                                           *
 *  Unless required by applicable law or agreed to in writing, software      *
 *  distributed under the License is distributed on an "AS IS" BASIS,        *
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
 *  See the License for the specific language governing permissions and      *
 *  limitations under the License.                                           *
 *                                                                           *
 ****************************************************************************/
 
/*============================ INCLUDES ======================================*/
 
#ifndef __VSF_TEST_H__
#   define __VSF_TEST_H__
 
#   include "component/vsf_component_cfg.h"
#   include "utilities/vsf_utilities.h"
 
/* example:
 
    // 0. Include vsf header file
    #include "vsf.h"
 
    // 1. Defining vsf_test variable
    static vsf_test_t __test = {
        .wdt =
            {
                .internal =
                    {
                        // 1.1 If you are using a device that already supports
                        // vsf_hal_wdt, then you can just use vsf_test_hal_wdt_*
                        .init = vsf_test_hal_wdt_init,
                        .feed = vsf_test_hal_wdt_feed,
                    },
                .external =
                    {
                        // 1.2 If you are using an assist device that can
                        // control the power pin or reset pin of the device,
                        // then you can use vsf_test_stdio_wdt_* to control it
                        .init = vsf_test_stdio_wdt_init,
                        .feed = vsf_test_stdio_wdt_feed,
                    },
            },
        .reboot =
            {
                // 1.3 Reset can be done using the functions provided by
                // vsf_arch or the chip's APIs
                .internal = vsf_arch_reset,
 
                // 1.4 To control the reset or power pins of the device, we can
                // use the stdio method to communicate.
                .external = vsf_test_stdio_reboot,
            },
        .data = {
            // We use stdio to communicate with assist devices for data
            // persistence. This way we only need to implement the stdio stub
            // function on the device to come.
            .init = vsf_test_stdio_data_init,
            .sync = vsf_test_stdio_data_sync,
        }};
    static vsf_test_t *test = &__test;
 
    // 3. Optionally, call vsf_test_reboot in the callback function for all
    // exceptions to abort the test and provide additional error messages if
    // possible information.
    // Here is an example of HardFault_Handler in Cortex-M:
    void HardFault_Handler(void)
    {
        vsf_test_reboot(VSF_TEST_RESULT_FAULT_HANDLER_FAIL, __FILE__,
                        __LINE__, __FUNCTION__, "More Info");
    }
 
    // 4. Here are some test examples. including:
    // - test succeeded
    // - test failed
    // - test with watchdog reset
    // - test with an exception
 
    // test succeeded
    static void __test_pass(void)
    {
        int a = 100;
        int b = 50 + 50;
 
        VSF_TEST_ASSERT(a == b);
    }
 
    // test failed
    static void __test_fail(void)
    {
        int a = 100;
        int b = 50 + 50;
 
        VSF_TEST_ASSERT(a != b);
    }
 
    // test with watchdog reset
    static void __test_wdt(void)
    {
        while (1);
    }
 
    // test with an exception, current only support cortex-m
    void __test_unalign(void)
    {
    #ifdef __CORTEX_M
        SCB->CCR |= (1 << 3);
        volatile uint32_t *p     = (volatile uint32_t *)0x03;
        uint32_t           value = *p;
    #else
    #    error "TODO"
    #endif
    }
 
    int main(void)
    {
        // 5. Configure and initialize the test framework
        vsf_test_cfg_t test_cfg = {
            .wdt = {
                .internal = {
                    .init = vsf_test_hal_wdt_init,
                    .feed = vsf_test_hal_wdt_feed,
                },
            },
            .reboot = {
                .internal = vsf_arch_reset,
            },
            .data = {
                .init = vsf_test_stdio_data_init,
                .sync = vsf_test_stdio_data_sync,
            },
            .restart_on_done = false,  // Set to true to restart when test completes or errors occur
        };
        vsf_test_init(&test_cfg);
 
        // 6. We support two styles of adding test cases.
        // - The first is the static way. We can use macros to initialize test
        //   cases. It is more RAM efficient.
        // - The second is the dynamic way of adding, which is closer to the
        //   traditional testing framework.
    #if 1
        vsf_test_add(__test_pass, "test_pass hw_req=none");
        vsf_test_add(__test_fail, "test_fail hw_req=none");
        vsf_test_add(__test_wdt, "test_wdt hw_req=none");
        vsf_test_add(__test_unalign, "test_invalid_address hw_req=none");
    #endif
 
        // 7. Here the test will start running
        vsf_test_run_tests();
 
        return 0;
    }
*/
 
 
 
#    if VSF_USE_TEST == ENABLED
 
/*============================ MACROS ========================================*/
 
#        ifndef VSF_TEST_CFG_LONGJMP
#            define VSF_TEST_CFG_LONGJMP ENABLED
#        endif
 
#        ifndef VSF_TEST_CFG_INTERNAL_TIMEOUT_MS
#            define VSF_TEST_CFG_INTERNAL_TIMEOUT_MS 1000
#        endif
 
#        ifndef VSF_TEST_CFG_EXTERNAL_TIMEOUT_MS
#            define VSF_TEST_CFG_EXTERNAL_TIMEOUT_MS 1500
#        endif
 
#        ifndef VSF_TEST_CFG_USE_HAL_WDT
#            define VSF_TEST_CFG_USE_HAL_WDT DISABLED
#        endif
 
#        ifndef VSF_TEST_CFG_USE_STDIO_DATA_SYNC
#            define VSF_TEST_CFG_USE_STDIO_DATA_SYNC DISABLED
#        endif
 
#        ifndef VSF_TEST_CFG_USE_FILE_DATA_SYNC
#            define VSF_TEST_CFG_USE_FILE_DATA_SYNC DISABLED
#        endif
 
#        ifndef VSF_TEST_CFG_USE_APPCFG_DATA_SYNC
#            define VSF_TEST_CFG_USE_APPCFG_DATA_SYNC DISABLED
#        endif
 
#        ifndef VSF_TEST_CFG_USE_TRACE
#            define VSF_TEST_CFG_USE_TRACE ENABLED
#        endif
 
#        ifndef VSF_TEST_CFG_ARRAY_SIZE
#            define VSF_TEST_CFG_ARRAY_SIZE 100
#        endif
 
#        define VSF_TEST_ASSERT(__v)                                           \
            do {                                                               \
                if (!(__v)) {                                                  \
                    __vsf_test_longjmp(VSF_TEST_RESULT_FAIL, __FILE__,         \
                                       __LINE__, __FUNCTION__, #__v);          \
                }                                                              \
            } while (0)
 
/*============================ TYPES =========================================*/
 
typedef enum vsf_test_status_t {
    VSF_TEST_STATUS_IDLE    = 0,
    VSF_TEST_STATUS_RUNNING = 1,
} vsf_test_status_t;
 
typedef enum vsf_test_req_t {
    VSF_TEST_REQ_NO_SUPPORT = 0,
    VSF_TEST_REQ_SUPPORT    = 1,
} vsf_test_req_t;
 
typedef enum vsf_test_result_t {
    VSF_TEST_RESULT_PASS               = 0x0u << 0,
    VSF_TEST_RESULT_SKIP               = 0x1u << 0,
    VSF_TEST_RESULT_WDT_PASS           = 0x2u << 0,
    VSF_TEST_RESULT_FAIL               = 0x3u << 0,
    VSF_TEST_RESULT_ASSERT_FAIL        = VSF_TEST_RESULT_FAIL,
    VSF_TEST_RESULT_WDT_FAIL           = 0x4u << 0,
    VSF_TEST_RESULT_ASSIST_FAIL        = 0x5u << 0,
    VSF_TEST_RESULT_FAULT_HANDLER_FAIL = 0x6u << 0,
} vsf_test_result_t;
 
typedef enum vsf_test_type_t {
    VSF_TEST_TYPE_LONGJMP_FN = 0,
    VSF_TEST_TYPE_BOOL_FN,
} vsf_test_type_t;
 
typedef void vsf_test_reboot_t(void);
 
typedef struct vsf_test_wdt_t vsf_test_wdt_t;
struct vsf_test_wdt_t {
    void (*init)(vsf_test_wdt_t *wdt, uint32_t timeout_ms);
    void (*feed)(vsf_test_wdt_t *wdt);
    uint32_t timeout_ms;
};
 
typedef enum vsf_test_data_cmd_t {
    VSF_TEST_STATUS_READ,
    VSF_TEST_STATUS_WRITE,
 
    VSF_TEST_TESTCASE_INDEX_READ,
    VSF_TEST_TESTCASE_INDEX_WRITE,
 
    VSF_TEST_TESECASE_REQUEST_WRITE,
 
    VSF_TEST_TESTCASE_RESULT_WRITE,
 
    VSF_TEST_DONE,
} vsf_test_data_cmd_t;
 
typedef struct vsf_test_data_t vsf_test_data_t;
struct vsf_test_data_t {
    void (*init)(vsf_test_data_t *data);
    void (*sync)(vsf_test_data_t *data, vsf_test_data_cmd_t cmd);
 
 
    uint32_t idx;
 
    uint32_t status;
 
    char *request_str;
    uint32_t req_continue;
 
    uint32_t result;
 
    struct {
        const char *function_name;
        const char *file_name;
        const char *condition;
        uint32_t    line;
    } error;
};
 
typedef bool vsf_test_bool_fn_t(void);
typedef void vsf_test_jmp_fn_t(void);
 
typedef struct vsf_test_case_t {
    union {
        vsf_test_bool_fn_t *b_fn;
 
        vsf_test_jmp_fn_t *jmp_fn;
    };
    char *cfg_str; // json or other configuration format
 
    uint8_t type;
 
    uint8_t expect_wdt;
 
    uint8_t expect_assert;
} vsf_test_case_t;
 
typedef struct vsf_test_cfg_t {
    struct {
        vsf_test_wdt_t internal;
        vsf_test_wdt_t external;
    } wdt;
 
    struct {
        vsf_test_reboot_t *internal;
        vsf_test_reboot_t *external;
    } reboot;
 
    struct {
        void (*init)(vsf_test_data_t *data);
        void (*sync)(vsf_test_data_t *data, vsf_test_data_cmd_t cmd);
    } data;
 
    bool restart_on_done;
} vsf_test_cfg_t;
 
typedef struct vsf_test_t {
    struct {
        vsf_test_wdt_t internal;
 
        vsf_test_wdt_t external;
    } wdt;
 
    struct {
        vsf_test_reboot_t *internal;
        vsf_test_reboot_t *external;
    } reboot;
 
    vsf_test_data_t data;
 
#        if VSF_TEST_CFG_LONGJMP == ENABLED
    jmp_buf *jmp_buf;
#        endif
 
    bool restart_on_done;
 
    uint32_t test_case_count;
    vsf_test_case_t test_case_array[VSF_TEST_CFG_ARRAY_SIZE];
} vsf_test_t;
 
/*============================ INCLUDES ======================================*/
/*============================ PROTOTYPES ====================================*/
 
extern void vsf_test_init(const vsf_test_cfg_t *cfg);
 
/*============================ API USAGE GUIDE =============================*/
extern bool vsf_test_add_ex(vsf_test_case_t *test_case);
 
extern bool vsf_test_add_simple_case(vsf_test_jmp_fn_t *jmp_fn, char *cfg);
 
extern bool vsf_test_add_bool_fn(vsf_test_bool_fn_t *b_fn, char *cfg);
 
extern bool vsf_test_add_case(vsf_test_jmp_fn_t *fn, char *cfg, uint8_t expect_wdt);
 
extern bool vsf_test_add_bool_fn_case(vsf_test_bool_fn_t *fn, char *cfg, uint8_t expect_wdt);
 
extern bool vsf_test_add_ex_case(vsf_test_jmp_fn_t *fn, char *cfg,
                                 vsf_test_type_t type,
                                 uint8_t expect_wdt,
                                 uint8_t expect_assert);
 
extern bool vsf_test_add_expect_assert_case(vsf_test_jmp_fn_t *fn,
                                            char *cfg,
                                            uint8_t expect_wdt);
 
extern void vsf_test_run_tests(void);
 
extern void __vsf_test_longjmp(vsf_test_result_t result,
                               const char *file_name, uint32_t line,
                               const char *function_name,
                               const char *condition);
 
extern void vsf_test_reboot(vsf_test_result_t result,
                            const char *file_name, uint32_t line,
                            const char *function_name,
                            const char *additional_str);
 
/*============================ LOCAL VARIABLES ===============================*/
/*============================ GLOBAL VARIABLES ==============================*/
 
/*============================ INCLUDES ======================================*/
 
#        include "./port/vsf_test_port_hal.h"
#        include "./port/vsf_test_port_stdio.h"
#        include "./port/vsf_test_port_file.h"
#        include "./port/vsf_test_port_appcfg.h"
 
#    endif
#endif
/* EOF */