esp-idf/components/driver/test/param_test/include/param_test.h
2021-05-24 01:06:17 +02:00

170 lines
7.1 KiB
C

/*
* SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
/*
* Parameterized Test Framework
*
* Peripherals like SPI has several parameters like: freq, mode, DMA, etc.
* This framework helps to test different parameter sets with the same program.
*
* Each "parameter set" is a set with different parameters (freq, mode, etc.).
* A parameter group is a group of several parameter sets. Each unit test performs
* tests among the sets in a group.
*
* The test will be execute in the following sequence:
* 1. ``pre_test``: initialize the context
* 2. take a set out of the parameter group
* 3. ``def_param``: fill in default value for the parameter set if not set
* 4. ``loop``: execute test program for the set in the initialized context
* 5. loop executing 2-4 until the last set
* 6. ``post_test``: free the resources used.
*
* Usage example:
*
* 1. Define your own parameter set type:
* typedef struct {
* const char pset_name[PSET_NAME_LEN];
* //The test work till the frequency below,
* //set the frequency to higher and remove checks in the driver to know how fast the system can run.
* const int *freq_list; // list of tested frequency, terminated by 0
* int freq_limit; //freq larger (not equal) than this will be ignored
* spi_dup_t dup;
* int mode;
* bool length_aligned;
* int test_size;
*
* int master_limit; // the master disable dummy bits and discard readings over this freq
* bool master_iomux;
* int master_dma_chan;
*
* bool slave_iomux;
* int slave_dma_chan;
* int slave_tv_ns;
* bool slave_unaligned_addr;
* } spitest_param_set_t;
*
* 2. Define a parameter set:
* spitest_param_set_t mode_pgroup[] = {
* //non-DMA tests
* { .pset_name = "mode 0, no DMA",
* .freq_list = test_freq_mode,
* .master_limit = FREQ_LIMIT_MODE,
* .dup = FULL_DUPLEX,
* .master_iomux= true,
* .slave_iomux = true,
* .slave_tv_ns = TV_WITH_ESP_SLAVE,
* .mode = 0,
* },
* { .pset_name = "mode 1, no DMA",
* .freq_list = test_freq_mode,
* .master_limit = FREQ_LIMIT_MODE,
* .dup = FULL_DUPLEX,
* .master_iomux= true,
* .slave_iomux = true,
* .slave_tv_ns = TV_WITH_ESP_SLAVE,
* .mode = 1,
* },
* // other configurations...
* };
*
* 3. Define your test functions, and wrap them in the ``param_test_func_t``:
* static const param_test_func_t master_test_func = {
* .pre_test = test_master_init,
* .post_test = test_master_deinit,
* .loop = test_master_loop,
* .def_param = spitest_def_param,
* };
*
* 4. Declare the group by PARAM_GROUP_DECLARE right after the param group:
* PARAM_GROUP_DECLARE(MODE, mode_pgroup)
*
* 5. Declare the test function by TEST_SINGLE_BOARD (for single board test), or TEST_MASTER_SLAVE(for multiboard test)
* TEST_MASTER_SLAVE(MODE, mode_pgroup, "[spi][timeout=120]", &master_test_func, &slave_test_func)
*
* or
* TEST_SINGLE_BOARD(TIMING, timing_pgroup, "[spi][timeout=120]", &local_test_func)
*
* NOTE: suggest to define your own macro to wrap 4 and 5 if your tag and test functions are the same. E.g.:
* #define TEST_SPI_MASTER_SLAVE(name, pgroup) (backslash)
* PARAM_GROUP_DECLARE(name, pgroup) (backslash)
* TEST_MASTER_SLAVE(name, pgroup, "[spi][timeout=120]", &master_test_func, &slave_test_func)
*
* Then declare tests conveniently by:
* TEST_SPI_MASTER_SLAVE(TIMING, timing_pgroup)
* TEST_SPI_MASTER_SLAVE(MODE, mode_pgroup)
*
*/
#define PGROUP_NAME_LEN 20 ///< name length of parameter group
#define PGROUP_NAME(name) PGROUP_##name ///< param group name
#define PTEST_MASTER_NAME(name) PTEST_MASTER_##name ///< test function name of master
#define PTEST_SLAVE_NAME(name) PTEST_SLAVE_##name ///< test function name of slave
/// Test set structure holding name, param set array pointer, item size and param set num.
typedef struct {
char name[PGROUP_NAME_LEN]; ///< Name of param group to print
void *param_group; ///< Start of the param group array
int pset_size; ///< Size of each param set
int pset_num; ///< Total number of param sets
} param_group_t;
/// Test functions for the frameowrk
typedef struct {
void (*pre_test)(void** contxt); ///< Initialization function called before tests begin. Initial your context here
void (*post_test)(void* context); ///< Deinit function called after all tests are done.
void (*def_param)(void* inout_pset); ///< Function to fill each pset structure before executed, left NULL if not used.
void (*loop)(const void* pset, void* context); ///< Function execute each param set
} ptest_func_t;
/**
* Test framework to execute init, loop and deinit.
*
* @param param_group Parameter group holder to test in turns.
* @param test_func Function set to execute.
*/
void test_serializer(const param_group_t *param_group, const ptest_func_t* test_func);
#define PARAM_GROUP_DECLARE_TYPE(group_name, pset_type, pgroup) \
static const param_group_t PGROUP_NAME(pgroup) = { \
.name = #group_name, \
.param_group = (void*)&pgroup, \
.pset_size = sizeof(pset_type), \
.pset_num = sizeof(pgroup)/sizeof(pset_type), \
};
/**
* Declare parameter group
*
* @param group_name Parameter group name to print in the beginning of the test
* @param param_group Parameter group structure, should be already defined above, and the size and type is defined.
*/
#define PARAM_GROUP_DECLARE(group_name, param_group) \
PARAM_GROUP_DECLARE_TYPE(group_name, typeof(param_group[0]), param_group)
/**
* Test parameter group on one board.
*
* @param name Test name to be printed in the menu.
* @param param_group Parameter group to be tested.
* @param tag Tag for environment, etc. e.g. [spi][timeout=120]
* @param test_func ``ptest_func_t`` to be executed.
*/
#define TEST_SINGLE_BOARD(name, param_group, tag, test_func) \
TEST_CASE("single board test: "#name, tag) { test_serializer(&PGROUP_NAME(param_group), test_func); }
/**
* Test parameter group for master-slave framework
*
* @param name Test name to be printed in the menu.
* @param param_group Parameter group to be tested.
* @param tag Tag for environment, etc. e.g. [spi][timeout=120]
* @param master_func ``ptest_func_t`` to be executed by master.
* @param slave_func ``ptest_func_t`` to be executed by slave.
*/
#define TEST_MASTER_SLAVE(name, param_group, tag, master_func, slave_func) \
static void PTEST_MASTER_NAME(name) (void) { test_serializer(&PGROUP_NAME(param_group), master_func); } \
static void PTEST_SLAVE_NAME(name) (void) { test_serializer(&PGROUP_NAME(param_group), slave_func); } \
TEST_CASE_MULTIPLE_DEVICES("master slave test: "#name, tag, PTEST_MASTER_NAME(name), PTEST_SLAVE_NAME(name))