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 ======================================*/
 
#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(test, 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(test, a == b);
    }
 
    // test failed
    static void __test_fail(void)
    {
        int a = 100;
        int b = 50 + 50;
 
        VSF_TEST_ASSERT(test, 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. 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
        static const vsf_test_case_t __test_cases[] = {
            VSF_TEST_ADD(__test_pass, "test_pass hw_req=none", 0),
            VSF_TEST_ADD(__test_fail, "test_fail hw_req=none", 0),
            VSF_TEST_ADD(__test_wdt, "test_wdt hw_req=none", 0),
            VSF_TEST_ADD(__test_unalign, "test_invalid_address hw_req=none", 0),
        };
        vsf_test_init(test, (vsf_test_case_t *)__test_cases,
                      dimof(__test_cases));
    #else static vsf_test_case_t __test_cases[10];
        vsf_test_init(test, __test_cases, dimof(__test_cases));
        vsf_test_add(test, __test_pass, "test_pass hw_req=none");
        vsf_test_add(test, __test_fail, "test_fail hw_req=none");
        vsf_test_add(test, __test_wdt, "test_wdt hw_req=none");
        vsf_test_add(test, __test_unalign, "test_invalid_address hw_req=none");
    #endif
 
        // 6. Here the test will start running
        vsf_test_run_tests(test);
 
        return 0;
    }
*/
 
#ifndef __VSF_TEST_H__
#    define __VSF_TEST_H__
 
#    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
 
#        define VSF_TEST_ASSERT(__t, __v)                                      \
            do {                                                               \
                if (!(__v)) {                                                  \
                    __vsf_test_longjmp(__t, VSF_TEST_RESULT_FAIL, __FILE__,    \
                                       __LINE__, __FUNCTION__, #__v);          \
                }                                                              \
            } while (0)
 
#        define VSF_TEST_ADD_EX(__FN, __CFG, __TYPE, ...)                      \
            {.jmp_fn = __FN, .cfg_str = __CFG, .type = __TYPE, __VA_ARGS__}
 
#        define VSF_TEST_ADD_BOOL_FN(__FN, __CFG, ...)                         \
            {.jmp_fn  = __FN,                                                  \
             .cfg_str = __CFG,                                                 \
             .type    = VSF_TEST_TYPE_BOOL_FN,                                 \
             __VA_ARGS__}
 
#        define VSF_TEST_ADD(__FN, __CFG, ...)                                 \
            {.jmp_fn  = __FN,                                                  \
             .cfg_str = __CFG,                                                 \
             .type    = VSF_TEST_TYPE_LONGJMP_FN,                              \
             __VA_ARGS__}
 
/*============================ 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;
} vsf_test_case_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
 
    struct {
        uint32_t         size;
        uint32_t         offset;
        vsf_test_case_t *array;
    } test_case;
} vsf_test_t;
 
/*============================ INCLUDES ======================================*/
/*============================ PROTOTYPES ====================================*/
 
extern void vsf_test_init(vsf_test_t *test, vsf_test_case_t *tc_array,
                          uint32_t array_size);
 
extern bool vsf_test_add_ex(vsf_test_t *test, vsf_test_case_t *test_case);
 
extern bool vsf_test_add(vsf_test_t *test, vsf_test_jmp_fn_t *jmp_fn,
                         char *cfg);
 
extern bool vsf_test_add_bool_fn(vsf_test_t *test, vsf_test_bool_fn_t *b_fn,
                                 char *cfg);
 
extern void vsf_test_run_tests(vsf_test_t *test);
 
extern void __vsf_test_longjmp(vsf_test_t *test, 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_t *test, 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"
 
#    endif
#endif
/* EOF */