michael/u-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

test: document ut.h

Browse Source 
Add missing Sphinx comments in include/test/ut.h

Reviewed-by: Simon Glass <sjg@chromium.org>
Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
This commit is contained in:
Heinrich Schuchardt
2025-11-18 21:17:31 +01:00
parent eb2d933a99
commit 8d18eac76d
1 changed files with 132 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
include/test/ut.h
View File

@@ -130,18 +130,28 @@ int ut_check_console_end(struct unit_test_state *uts);
*
* This only supports a byte dump.
*
* @total_bytes: Size of the expected dump in bytes`
* Return: 0 if OK (looks like a dump and the length matches), other value on
* error
* @uts: Test state
* @total_bytes: Size of the expected dump in bytes
* Return: 0 if OK (looks like a dump and the length matches),
* other value on error
*/
int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
/* Report a failure, with printf() string */
/**
* ut_report() - Report a failure, with printf() string
*
* @fmt: format string
* @args: arguments to be printed
*/
#define ut_reportf(fmt, args...) \
ut_failf(uts, __FILE__, __LINE__, __func__, "report", \
fmt, ##args)
/* Assert that a condition is non-zero */
/**
* ut_assert() - Assert that a condition is true (not 0)
*
* @cond: condition
*/
#define ut_assert(cond) ({ \
int __ret = 0; \
\
@@ -152,7 +162,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that a condition is non-zero, with printf() string */
/**
* ut_assertf() - Assert that a condition is true with printf string
*
* @cond: condition
* @fmt: format string
* @args: arguments to be printed
*/
#define ut_assertf(cond, fmt, args...) ({ \
int __ret = 0; \
\
@@ -164,7 +180,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that two int expressions are equal */
/**
* ut_asserteq() - Assert that two int32 expressions are equal
*
* @expr1: expected value
* @expr2: actual value
*/
#define ut_asserteq(expr1, expr2) ({ \
unsigned int _val1 = (expr1), _val2 = (expr2); \
int __ret = 0; \
@@ -179,7 +200,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that two 64 int expressions are equal */
/**
* ut_asserteq_64() - Assert that two int64 expressions are equal
*
* @expr1: expected value
* @expr2: actual value
*/
#define ut_asserteq_64(expr1, expr2) ({ \
u64 _val1 = (expr1), _val2 = (expr2); \
int __ret = 0; \
@@ -197,7 +223,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that two string expressions are equal */
/**
* ut_asserteq_str() - Assert that two string expressions are equal
*
* @expr1: expected value
* @expr2: actual value
*/
#define ut_asserteq_str(expr1, expr2) ({ \
const char *_val1 = (expr1), *_val2 = (expr2); \
int __ret = 0; \
@@ -211,9 +242,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/*
* Assert that two string expressions are equal, up to length of the
* first
/**
* ut_asserteq_strn() - Assert that two string expressions are equal
* up to the length of the first expression
*
* @expr1: expected value
* @expr2: actual value
*/
#define ut_asserteq_strn(expr1, expr2) ({ \
const char *_val1 = (expr1), *_val2 = (expr2); \
@@ -230,7 +264,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that two memory areas are equal */
/**
* ut_asserteq_mem() - Assert that two memory areas are equal
*
* @expr1: expected value
* @expr2: actual value
* @len: length of the memory areas
*/
#define ut_asserteq_mem(expr1, expr2, len) ({ \
const u8 *_val1 = (u8 *)(expr1), *_val2 = (u8 *)(expr2); \
const uint __len = len; \
@@ -250,7 +290,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that two pointers are equal */
/**
* ut_asserteq_ptr() - Assert that two string pointers are equal
*
* @expr1: expected value
* @expr2: actual value
*/
#define ut_asserteq_ptr(expr1, expr2) ({ \
const void *_val1 = (expr1), *_val2 = (expr2); \
int __ret = 0; \
@@ -264,7 +309,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that two addresses (converted from pointers) are equal */
/**
* ut_asserteq_addr() - Assert that two addresses (converted from pointers)
* are equal
*
* @expr1: expected value
* @expr2: actual value
*/
#define ut_asserteq_addr(expr1, expr2) ({ \
ulong _val1 = map_to_sysmem(expr1); \
ulong _val2 = map_to_sysmem(expr2); \
@@ -279,7 +330,11 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that a pointer is NULL */
/**
* ut_assertnull() - Assert that a pointer is NULL
*
* @expr: pointer
*/
#define ut_assertnull(expr) ({ \
const void *_val = (expr); \
int __ret = 0; \
@@ -293,7 +348,11 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that a pointer is not NULL */
/**
* ut_assertnonnull() - Assert that a pointer is not NULL
*
* @expr: pointer
*/
#define ut_assertnonnull(expr) ({ \
const void *_val = (expr); \
int __ret = 0; \
@@ -307,7 +366,11 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that a pointer is not an error pointer */
/**
* ut_assertok_ptr() - Assert that a pointer is not an error pointer
*
* @expr: pointer
*/
#define ut_assertok_ptr(expr) ({ \
const void *_val = (expr); \
int __ret = 0; \
@@ -322,10 +385,19 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that an operation succeeds (returns 0) */
/**
* ut_assertok() - Assert that an operation succeeds (returns 0)
*
* @cond: expression
*/
#define ut_assertok(cond) ut_asserteq(0, cond)
/* Assert that the next console output line matches */
/**
* ut_assert_nextline() - Assert that the next console output line matches
*
* @fmt: format string
* @args: print arguments
*/
#define ut_assert_nextline(fmt, args...) ({ \
int __ret = 0; \
\
@@ -338,7 +410,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that the next console output line matches up to the length */
/**
* ut_assert_nextlinen() - Assert that the next console output line matches
* up to the length of the expected string.
*
* @fmt: format string
* @args: print arguments
*/
#define ut_assert_nextlinen(fmt, args...) ({ \
int __ret = 0; \
\
@@ -351,7 +429,10 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that there is a 'next' console output line, and skip it */
/**
* ut_assert_skipline() - Assert that there is a 'next' console output line,
* and skip it
*/
#define ut_assert_skipline() ({ \
int __ret = 0; \
\
@@ -363,7 +444,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that a following console output line matches */
/**
* ut_assert_skip_to_line() - Assert that a following console output line
* matches
*
* @fmt: format string
* @args: print arguments
*/
#define ut_assert_skip_to_line(fmt, args...) ({ \
int __ret = 0; \
\
@@ -376,7 +463,13 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that a following console output line matches */
/**
* ut_assert_skip_to_linen() - Assert that a following console output line
* matches up to the length of the expected string
*
* @fmt: format string
* @args: print arguments
*/
#define ut_assert_skip_to_linen(fmt, args...) ({ \
int __ret = 0; \
\
@@ -389,7 +482,9 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that there is no more console output */
/**
* ut_assert_console_end() - Assert that there is no more console output
*/
#define ut_assert_console_end() ({ \
int __ret = 0; \
\
@@ -402,7 +497,12 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that the next lines are print_buffer() dump at an address */
/**
* ut_assert_nextlines_are_dump - Assert that the next lines are print_buffer()
* dump at an address
*
* @total_bytes: Size of the expected dump in bytes
*/
#define ut_assert_nextlines_are_dump(total_bytes) ({ \
int __ret = 0; \
\
@@ -416,7 +516,10 @@ int ut_check_console_dump(struct unit_test_state *uts, int total_bytes);
__ret; \
})
/* Assert that the next console output line is empty */
/**
* ut_assert_nextline_empty() - Assert that the next console output line is
* empty
*/
#define ut_assert_nextline_empty() \
ut_assert_nextline("%s", "")
@@ -451,6 +554,8 @@ void ut_silence_console(struct unit_test_state *uts);
*
* This restarts console output again and turns off console recording. This
* happens on all boards, including sandbox.
*
* @uts: Test state
*/
void ut_unsilence_console(struct unit_test_state *uts);