From 9dee40527b352ebbe386a178cea3a374673a00a2 Mon Sep 17 00:00:00 2001 From: Cyril Hrubis Date: Tue, 24 Feb 2015 13:31:14 +0100 Subject: lib: Add tst_timer functions. * Add struct timespec conversions and arithmetic * Add timer functions simplify elapsed time measurement. Signed-off-by: Cyril Hrubis --- doc/test-writing-guidelines.txt | 73 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) (limited to 'doc') diff --git a/doc/test-writing-guidelines.txt b/doc/test-writing-guidelines.txt index e2b455ec7..27041190d 100644 --- a/doc/test-writing-guidelines.txt +++ b/doc/test-writing-guidelines.txt @@ -1048,6 +1048,79 @@ const char *const cmd[] = { "ls", "-l", NULL }; ... ------------------------------------------------------------------------------- +2.2.21 Measuring elapsed time and helper functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[source,c] +------------------------------------------------------------------------------- +#include "test.h" + +void tst_timer_check(clockid_t clk_id); + +void tst_timer_start(clockid_t clk_id); + +void tst_timer_stop(void); + +struct timespec tst_timer_elapsed(void); + +long long tst_timer_elapsed_ms(void); + +long long tst_timer_elapsed_us(void); +------------------------------------------------------------------------------- + +The 'tst_timer_check()' function checks if specified 'clk_id' is suppored and +exits the test with 'TCONF' otherwise. It's expected to be used in test +'setup()' before any resources that needs to be cleaned up are initialized, +hence it does not include a cleanup function parameter. + +The 'tst_timer_start()' marks start time and stores the 'clk_id' for further +use. + +The 'tst_timer_stop()' marks the stop time using the same 'clk_id' as last +call to 'tst_timer_start()'. + +The 'tst_timer_elapsed*()' returns time difference between the timer start and +last timer stop in serveral formats and units. + +IMPORTANT: The timer functions use 'clock_gettime()' internally which needs to + be linked with '-lrt' on older glibc. Please do not forget to add + 'LDLIBS+=-lrt' in Makefile. + +[source,c] +------------------------------------------------------------------------------- +long long tst_timespec_to_us(struct timespec t); +long long tst_timespec_to_ms(struct timespec t); + +int tst_timespec_lt(struct timespec t1, struct timespec t2); + +struct timespec tst_timespec_add_us(struct timespec t, long long us); + +struct timespec tst_timespec_diff(struct timespec t1, struct timespec t2); +long long tst_timespec_diff_us(struct timespec t1, struct timespec t2); +long long tst_timespec_diff_ms(struct timespec t1, struct timespec t2); + +struct timespec tst_timespec_abs_diff(struct timespec t1, struct timespec t2); +long long tst_timespec_abs_diff_us(struct timespec t1, struct timespec t2); +long long tst_timespec_abs_diff_ms(struct timespec t1, struct timespec t2); +------------------------------------------------------------------------------- + +The first two functions 'tst_timespec_to_us()' and 'tst_timespec_to_ms()' are +simple conversion inline functions. + +The 'tst_timespec_lt()' function returns non-zero if 't1' is earlier than +'t2'. + +The 'tst_timespec_add_us()' function adds 'us' microseconds to the timespec +'t'. The 'us' is expected to be positive. + +The 'tst_timespec_diff*()' functions returns difference between two times, the +'t1' is expected to be later than 't2'. + +The 'tst_timespec_abs_diff*()' functions returns absolute value of difference +between two times. + +NOTE: All conversions to ms and us rounds the value. + 2.3 Writing a testcase in shell ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3