tftf/framework/include/tftf.h

/*
 * Copyright (c) 2018, Arm Limited. All rights reserved.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

#ifndef __TFTF_H__
#define __TFTF_H__

#ifndef __ASSEMBLY__
#include <status.h>
#include <stddef.h>
#include <tftf_lib.h>

#define TFTF_WELCOME_STR	"Booting trusted firmware test framework"

/* Maximum size of test output (in bytes) */
#define TESTCASE_OUTPUT_MAX_SIZE	1024

/* Size of build message used to differentiate different TFTF binaries */
#define BUILD_MESSAGE_SIZE 		0x20

extern const char build_message[];

typedef test_result_t (*test_function_t)(void);

typedef struct {
	/* Test result (success, crashed, failed, ...). */
	test_result_t		result;
	unsigned long long	duration;
	/*
	 * Offset of test output string from TEST_NVM_RESULT_BUFFER_OFFSET.
	 * Only relevant if test has an output, i.e. if \a output_size is not
	 * zero.
	 */
	unsigned		output_offset;
	/* Size of test output string, excluding final \0. */
	unsigned		output_size;
} TESTCASE_RESULT;

typedef struct {
	unsigned		index;
	const char		*name;
	const char		*description;
	test_function_t		test;
} test_case_t;

typedef struct {
	const char		*name;
	const char		*description;
	const test_case_t	*testcases;
} test_suite_t;

/*
 * Reference to a specific test.
 */
typedef struct {
	unsigned int		testsuite_idx;
	unsigned int		testcase_idx;
} test_ref_t;

/*
 * The progress in the execution of a test.
 * This is used to implement the following state machine.
 *
 *  +-> TEST_READY (initial state of the test)                  <--------------+
 *  |        |                                                                 |
 *  |        |  Test framework prepares the test environment.                  |
 *  |        |                                                                 |
 *  |        v                                                                 |
 *  |   TEST_IN_PROGRESS                                                       |
 *  |        |                                                                 |
 *  |        |  Hand over to the test function.                                |
 *  |        |  If the test wants to reboot the platform  ---> TEST_REBOOTING  |
 *  |        |  Test function returns into framework.                |         |
 *  |        |                                                       | Reboot  |
 *  |        |                                                       |         |
 *  |        |                                                       +---------+
 *  |        v
 *  |   TEST_COMPLETE
 *  |        |
 *  |        |  Do some framework management.
 *  |        |  Move to next test.
 *  +--------+
 */
typedef enum {
	TEST_PROGRESS_MIN = 0,
	TEST_READY = TEST_PROGRESS_MIN,
	TEST_IN_PROGRESS,
	TEST_COMPLETE,
	TEST_REBOOTING,

	TEST_PROGRESS_MAX,
} test_progress_t;

#define TEST_PROGRESS_IS_VALID(_progress)	\
	((_progress >= TEST_PROGRESS_MIN) && (_progress < TEST_PROGRESS_MAX))

/*
 * The definition of this global variable is generated by the script
 * 'tftf_generate_test_list' during the build process
 */
extern const test_suite_t testsuites[];

extern TESTCASE_RESULT testcase_results[];

/* Set/Get the test to run in NVM */
STATUS tftf_set_test_to_run(const test_ref_t test_to_run);
STATUS tftf_get_test_to_run(test_ref_t *test_to_run);
/* Set/Get the progress of the current test in NVM */
STATUS tftf_set_test_progress(test_progress_t test_progress);
STATUS tftf_get_test_progress(test_progress_t *test_progress);

/**
** Save test result into NVM.
*/
STATUS tftf_testcase_set_result(const test_case_t *testcase,
				test_result_t result,
				unsigned long long duration);
/**
** Get a testcase result from NVM.
**
** @param[in]  testcase The targeted testcase.
** @param[out] result Testcase result. Only \a result.result and
**   \a result.duration are of interest for the caller and the 2 other fields
**   should be ignored (they correspond to a location in NVM).
** @param[out] test_output Buffer to store the test output, if any.
**   \a test_output must be big enough to hold the whole test output.
**   Test output will be \a TESTCASE_OUTPUT_MAX_SIZE bytes maximum.
*/
STATUS tftf_testcase_get_result(const test_case_t *testcase, TESTCASE_RESULT *result, char *test_output);

void print_testsuite_start(const test_suite_t *testsuite);
void print_test_start(const test_case_t *test);
void print_test_end(const test_case_t *test);
void print_tests_summary(void);

/*
 * Exit the TFTF.
 * This function can be used when a fatal error is encountered or as part of the
 * normal termination process. It does the necessary cleanups then put the
 * core in a low-power state.
 */
void __dead2 tftf_exit(void);

void tftf_arch_setup(void);

/*
 * This function detects the power state format used by PSCI which can
 * be either extended or original format. For the Original format,
 * the State-ID can either be NULL or can be using the recommended encoding.
 * This function needs to be invoked once during cold boot prior to the
 * invocation of any PSCI power state helper functions.
 */
void tftf_detect_psci_pstate_format(void);

/*
 * Run the next test on the calling CPU.
 * Once the test is complete, if the calling CPU is the last one to exit the
 * test then do the necessary bookkeeping, report the overall test result and
 * move on to the next test. Otherwise, shut down the calling CPU.
 *
 * This function never returns.
 */
void __dead2 run_tests(void);

/* Entry point for a CPU that has just been powered up */
void tftf_hotplug_entry(void);

#endif /*__ASSEMBLY__*/

#endif