Skip to ContentSun and Oracle Channel Sun How to Buy Log In

XIL Test Suite User's Guide

Contained Within

Find More Documentation

Featured Support Resources

Scarica il manuale in formato PDF

Writing Test Programs in the XIL Test Suite Environment

3

This chapter provides the information you need to write test programs to verify new functionality (for example, a new molecule) that you have added to the XIL library. For information on how to add functionality to the XIL library, see the XIL Device Porting and Extensibility Guide.

dl>

Example Test Program

As described in Chapter 2, "Running Test Programs in the XIL Test Suite," all test programs use calls to the XIL library and to the XIL Test Suite library (libts) to verify that test programs produce signatures or data identical to the stored reference signatures or data. The functions available in libts are described in detail later in this chapter.

The simple example of a test program in Code Example 3-1 gives you an idea of what such a program should do. The program image_example_test.c tests the XIL library function xil_add(). The full text of this program is in Appendix B, "Example Test Program." The program itself is located in the $XILCHHOME/../src/tests/examples directory.

After the usual declarations (notice that a tolerance of 0.0 is specified, meaning that results from the test program must match the stored reference), the first thing any test program must do is open the XIL library with xil_open() and the XIL Test Suite library with ts_init(), and start the test case with ts_start_test_case().

Code Example 3-1 Test Program Example: Initializing the Libraries


  #include <stdio.h>  
  #include <stdlib.h>  
  #include <string.h>  
  #include <xil/xil.h>  
  #include <xilch/ts.h>  
  
  main (  
  int argc,  
  char**argv )  
  {  
   int         i;  
   int         errors = 0;  
   int         total_errors = 0;  
   char        *specfile = NULL;  
   float       tol = 0.0;  
   XilImage        src1, src2, dst1;  
   XilSystemState                    xil_State;  
  
   /*  
   * process command line arguments  
   */  
  
   for (i = 1; i < argc; i++) {  
       if (!strcmp (argv[i], "-m")) {  
           specfile = argv[++i];  
       }  
       if (!strcmp (argv[i], "-tol")) {  
           tol = atof (argv[++i]);  
       }  
   }  
  
   /*  
   * initialize XIL and the test suite library  
   */

Code Example 3-1 Test Program Example: Initializing the Libraries (Continued)


   if ((xil_State = xil_open ()) == (XilSystemState) NULL) {  
       fprintf (stderr, "Error initializing XIL\n");  
       exit (1);  
   }  
  
   if (ts_init (&argc, argv, xil_State) == TS_FAILURE) {  
       exit (1);  
   }  
  ts_start_case("image_example_test");

Next, the program retrieves the images it needs for testing with calls to ts_get_src[123]_image and ts_get_dst[123]_image.


   /*  
   * get some test images  
   */  
  
   src1 = ts_get_src1_image (specfile);  
   src2 = ts_get_src2_image (specfile);  
   dst1 = ts_get_dst1_image (specfile);

These functions retrieve test images as specified in the test matrix file specfile. If a file name had not been specified (specfile == NULL), the default test matrix file, xilch_tests, would have been used.

After a call to the XIL function you are testing (in this case, xil_add()), the next step is to verify your results with a call to ts_verify(). When the test program gets to the ts_verify() call, the test signature or data is compared to the stored reference.

This part of the program does one other thing. It contains a loop to call a series of images, rather than just one set of images. The loop continues to retrieve images from specfile, the test matrix file, until all the images in that file have been retrieved.

Code Example 3-2 contains the loop with the call to ts_verify(). Note that the function's comment parameter does not have to be NULL. (This parameter puts a comment in the log file.)

Code Example 3-2 Test Program Example: Looping over Images in the Test Matrix File


  /*  
   * loop over the images in the test matrix file  
   */  
   while ( (src1 != (XilImage) NULL) &&  
        (src2 != (XilImage) NULL) &&  
        (dst1 != (XilImage) NULL) ) {  
       /*  
        * do the operation(s), add two images into a destination  
        */  
       xil_add (src1, src2, dst1);  
       /*  
        * verify the results  
        */  
       errors = ts_verify ("add", NULL, dst1, tol, NULL);  
       if (errors != 0) {  
           /*  
           * save the src and dst images for further study  
           */  
           ts_save (src1, "add_src1");  
           ts_save (src2, "add_src2");  
           ts_save (dst1, "add_dst");  
           total_errors++;  
           exit (total_errors);  
       }  
       /*  
        * get rid of the images  
        */  
       ts_destroy (src1);

Code Example 3-2 Test Program Example: Looping over Images in the Test Matrix File (Continued)


       ts_destroy (src2);  
       ts_destroy (dst1);  
  
       /*  
        * get some more test images  
        */  
  
       src1 = ts_get_src1_image (specfile);  
       src2 = ts_get_src2_image (specfile);  
       dst1 = ts_get_dst1_image (specfile);  
  
   }

The final part of the program ends the test case, and closes the XIL Test Suite library and the XIL library.


   /*  
   * return the total number of errors (required) and close XIL  
   */  
   ts_end_test_case();  
   xil_close (xil_State);  
  
   total_errors = ts_end ();  
  
   exit (total_errors);  
  }

As you have seen, this example program gives you a basic idea of the kinds of things you need to include in test programs you might develop. These include:

Calls to initialize the relevant libraries.
Calls to retrieve the images that will be used.
Calls to the functionality you are testing.
Calls to ts_verify() to compare the results of your test program to the stored reference.

Calls to close the relevant libraries.

Available XIL Test Suite Library Functions

The XIL Test Suite library provides many more functions than the ones used in this example program.Table 3-1 lists all the functions available in libts by function category. Syntax and usage of these functions are described in detail at the end of this chapter.

Table 3-1 libts (1 of 3)

Function Category	Function Name
General Functions	`ts_init()` `ts_end()` `ts_benchmark_start()` `ts_benchmark_end()` `ts_expect_errors()` `ts_log()` `ts_start_test_case()` `ts_end_test_case()`
Image Functions	`ts_verify()` `ts_getref()` `ts_compare()` `ts_image_gen()` `ts_load()` `ts_save()` `ts_checksum()` `ts_get_src1_image()` `ts_get_src2_image()` `ts_get_src3_image()` `ts_get_dst1_image()` `ts_get_dst2_image()` `ts_get_dst3_image()` `ts_get_complex_roi()`

Table 3-1 libts (2 of 3)

Function Category	Function Name
	`ts_destroy()` `ts_display()`
Lookup Table Functions	`ts_lookup_verify()` `ts_lookup_verify_contents()` `ts_lookup_getref()` `ts_lookup_compare()` `ts_lookup_compare_contents()` `ts_lookup_contents_checksum()` `ts_lookup_load()` `ts_lookup_save()`
CIS Functions	`ts_cis_verify()` `ts_cis_getref()` `ts_cis_compare()` `ts_cis_checksum()` `ts_cis_load()` `ts_cis_save()` `ts_cis_destroy()`
Float and Integer Functions	`ts_float_verify()` `ts_float_getref()` `ts_float_load()` `ts_float_save()` `ts_int_verify()` `ts_int_getref()` `ts_int_load()` `ts_int_save()`

Table 3-1 libts (3 of 3)

Function Category	Function Name
Equivalence Testing Functions	`ts_automatic_tests()` `ts_verify_needed()` `ts_child_check()` `ts_roi_check()`

Other Useful Examples

In the same directory with image_test_example.c are two other examples that might be useful:

$XILCHHOME/../src/tests/examples/example_bench.c
A simple benchmarking program
$XILCHHOME/../src/tests/examples/Makefile
An example Makefile

The examples subdirectory also includes the source code for two typical test programs: fax_test.c and rotate_test.c.

See the section "Writing and Using Benchmarking Programs" for details on benchmarking programs.

After You Write Your Test Program

When you write your own test program, you cannot use the references shipped with the XIL Test Suite to verify XIL functions; you must create your own references that correspond to the new test program.

Unless you use the image data provided in the xilch_tests test matrix file, you will need to create your own test matrix for your test program to use. This data must conform to the test matrix file format, which is described in Chapter 2, "Running Test Programs in the XIL Test Suite."

After you have created your test matrix file and written your test program, you should run your program alone (not under Xilch) to debug it. This procedure is described in Chapter 2, "Running Test Programs in the XIL Test Suite."

To build your test program, you must link with the following libraries: libts, libfileio, libvff, libxil, and libm. For an example, see the Makefile in $XILCHHOME/../src/tests/examples.

Writing and Using Benchmarking Programs

You can write benchmarking programs with XIL Test Suite library functions that will measure the performance, in frames per second, of a given XIL function. As mentioned earlier, source for an example benchmarking program is located in $XILCHHOME/../src/tests/examples/example_bench.c.

Here's the code for a simple benchmarking function that tests the performance of xil_threshold():


  /*  
   * benchmark loop  
   */  
  ts_benchmark_start ("threshold");  
  for (j = 0; j < iterations; j++) {  
       xil_threshold (src1, src1, lowvalue, highvalue, mapvalue);  
       xil_sync (src1);  
  }  
  ts_benchmark_end (iterations, comment);

The libts function ts_benchmark_start() is used to get the starting time of the program, and ts_benchmark_end() gets the time the program ended, and calculates how many frames per second xil_threshold() takes to run.

You get more accurate results if you specify a fairly high number for iterations, because this lessens the impact of program overhead. You specify the number of iterations on the command line. The xil_sync() call is needed to prevent the operation from being deferred.

Running Your Benchmarking Program

You can run your benchmarking program in several ways. The simplest way is to run it outside of Xilch. For example, if your program name were bench and you wanted to run it for 20 iterations, you would type the following at the command line:

% bench -I 20

The output gives you the performance of the function that bench tests.

Or you could run your program through Xilch. To do this, type:

% Xilch -t "bench -I 20"

The output gives you the performance of the function that bench tests.

Running your benchmarking programs through Xilch gives you one advantage over running the programs outside of Xilch--you can create a testlist file containing all your benchmarking programs and use the -f Xilch option to run that file. For example, suppose you had a testlist file called benches that contained your benchmarking programs. To run them all through Xilch, type:

% Xilch -f benches

Of course, you could vary the number of iterations by specifying them for individual programs in your testlist file.

Using Equivalence Testing Functions

The XIL Test Suite library provides a set of functions that enables the test writer to test certain XIL features (such as child images and ROIs) without requiring any visual verification. These functions are:

ts_child_check()
ts_roi_check()
ts_automatic_tests()

These functions produce a "reference result" and a "test result." (These functions do not test against reference signatures or data). These two results should be identical if the XIL feature under test is working correctly. These

functions use the FUNCFORMAT structure to receive descriptions of XIL operations. See Appendix C, "Equivalence Testing Example," for an example of how to use these functions.

The Test Suite Library

The Test Suite library, libts, provides functions to aid the test program writer in activities such as verifying images, generating test images, and logging test information. These functions are divided into categories (general, image, lookup table, CIS, float and integer, and equivalence testing functions) and are described on the following pages.

Include Files

The file <xilch/ts.h> must be included after <xil/xil.h>.

General Functions

`ts_init`

int ts_init (int *argc, char **argv, XilSystemState xil_state);

Description

ts_init() initializes the Test Suite library. It handles the command line arguments specific to the Test Suite library, which include the options -f, -r, and -t. This function must be called before any other Test Suite functions and after xil_open(3) has been called. If it is successful, ts_init() returns TS_SUCCESS. Otherwise, it returns TS_FAILURE.

Parameters

*argc*	The number of command-line arguments the program was invoked with.
*argv*	A pointer to an array of character strings that contain the arguments, one per string.
*xil_state*	The system state created when `xil_open` is invoked

`ts_end`

int ts_end ();

Description

ts_end() releases the Test Suite library and all of its resources. It should be called at the end of the test program. If it is successful, ts_end() returns TS_SUCCESS; otherwise, it returns TS_FAILURE.

Note - This function does not destroy images when it is called. You must call ts_destroy() to destroy images.

`ts_benchmark_start`

int ts_benchmark_start (char *funcname);

Description

ts_benchmark_start() marks the beginning of benchmark code and starts a timer. Appropriate entries are made in the log file. This function returns the time it started.

Parameters

funcname....A string containing the name of the function being benchmarked.

`ts_benchmark_end`

int ts_benchmark_end (int iterations, char *comment);

Description

ts_benchmark_end() marks the end of benchmark code. Appropriate entries are made in the log file. The function ts_benchmark_end() returns the elapsed time since the last call to ts_benchmark_start().

Parameters

*iterations*	The number of command-line arguments the program was invoked with.
*comment*	A string containing a comment written to the log file if verbose mode is on. The string can be NULL.

`ts_expect_errors`

void ts_expect_errors (int linenum, char *error_str, char
*error_str, ..., NULL);

Description

ts_expect_errors() installs an XIL error handler and begins looking for the "expected" errors to occur.

Parameters This function accepts a variable number of arguments terminated by a NULL.

*linenum*	The current line number. Usually this parameter is the macro `__LINE__`.
*error_str*	XIL error strings that identify expected errors. These strings are of the form `di`*-number*.

`ts_log`

int ts_log (char *comment);

Description

ts_log() writes the supplied comment to the log file if verbose mode is on. It returns TS_SUCCESS if it is successful; otherwise, it returns TS_FAILURE.

Parameters

comment....A string containing a comment written to the log file if verbose mode is on. The string can be NULL.

`ts_start_test_case`

int ts_start_test_case (char *test_case_name);

Description

ts_start_test_case() starts a test case.

Parameters

test_case_name The name of the test case. The name must be unique in the Test Suite.

`ts_end_test_case`

void ts_end_test_case ();

Description

ts_end_test_case() ends a test case.

Image Functions

`ts_verify`

int ts_verify (char *funcname, char *comment, XilImage im,
float tolerance, char *ref_name);

Description

ts_verify() verifies a test program against stored reference signatures or data. This function returns the number of differences it finds.

Note - As a debugging aid, the environment variable XILCHSAVE can be used to save the two images that were verified against each other and the last source images retrieved via ts_get_src[123]_image(). The format of XILCHSAVE is a list of numbers separated by a colon, where the numbers represent the images that are a result of calls to ts_verify() that you want to save. The count starts at 0. For example, if you had 5 calls to ts_verify() and you wanted to save the images from the first and fourth calls, XILCHSAVE would look like this: 0:3.

Parameters

*funcname*	A string containing the name of the function that generated the image to be verified.
*comment*	A string containing a comment written to the log file if verbose mode is on. It can be NULL.
im	The name of the image to be verified.
*tolerance*	Specifies a tolerance to be used in the comparison.
*ref_name*	Specifies the reference name that the library uses. If *ref_name* is NULL, the library uses a default name for the reference. Explicit naming is useful when a variable number of verifications is performed within a single test case or when `ts_getref()` is used (see `ts_getref()`). *ref_name* must be unique within the test case.

The library assigns default reference names in the following way. The call to ts_start_ref() initializes the default reference name to "r.0." Each call to ts_*_verify() that has NULL specified as ref_name will increment the default reference name. For example, the reference name used in the first call to ts_*_verify() that has NULL specified as ref_name is "r.1" and the second is "r.2." When you supply a reference name, you should not specify a default name. When Xilch is run in verbose mode, reference names are printed to the log file.

`ts_getref`

XilImage ts_getref ();

Description

ts_getref() retrieves reference data, if any. It returns NULL if there is no reference data. The reference data it retrieves is the data named by the current default reference name--the reference name used by the most recent call to ts_*_verify() in the current test case. See ts_verify() for an explanation

of reference names. If you call ts_getref() before calling ts_verify() in the current test case, NULL is returned. You cannot call ts_getref() outside a test case.

`ts_compare`

int ts_compare (XilImage im1, XilImage im2, float tolerance);

Description

ts_compare() compares two images. It returns the number of differences it finds.

Parameters

*im1* and *im2*	The names of the images to be compared.
*tolerance*	Specifies a tolerance to be used in the comparison.

`ts_image_gen`

int ts_image_gen (XilImage im, int type, int *value);

Description

ts_image_gen() generates an image from a set of predefined image types.

Parameters

im	The previously created image handle. `ts_image_gen()` returns `TS_SUCCESS` if it is successful; otherwise, it returns `TS_FAILURE`.
*type*	One of the following: TS_RANDOM, TS_CONSTANT, or TS_RAMP.
*value*	A pointer to a vector that specifies the random number seed for TS_RANDOM, or the constant value for TS_CONSTANT. *value* is not used with TS_RAMP. This vector should match in size with the number of bands in the image im.

`ts_load`

XilImage ts_load (char *filename);

Description

ts_load() loads the image from a file and returns a handle to that image if successful. Otherwise, it returns NULL. Currently, this function only handles images in .vff format. This is an unsupported, Sun-internal file format. The file format accepted by this function may change in future releases.

Parameters

filename.....The name of the file from which ts_load() loads the image.

`ts_save`

int ts_save (XilImage im, char *filename);

Description

ts_save() saves an image into a file. Images are saved in .vff format. If this function runs successfully, it returns the value 0 (zero); otherwise, it returns the value 1.

Parameters

im	The name of the image being saved.
*filename*	The name of the file into which `ts_save()` saves the image.

`ts_checksum`

unsigned int ts_checksum (XilImage im);

Description

ts_checksum() returns a 32-bit CRC code for an image.

Parameters

im.......The name of the image on which to perform a checksum calculation.

`ts_get_src[123]_image` and `ts_get_dst[123]_image`

XilImage ts_get_src1_image (char *filename);
XilImage ts_get_src2_image (char *filename);
XilImage ts_get_src3_image (char *filename);
XilImage ts_get_dst1_image (char *filename);
XilImage ts_get_dst2_image (char *filename);
XilImage ts_get_dst3_image (char *filename);

Description

ts_get_src[123]_image() and ts_get_dst[123]_image retrieve test images from a test matrix file. ts_get_src[123]_image and ts_get_dst[123]_image return images each time they are called until there are no more images specified in the test matrix file, at which time they return NULL. The next call after a returned NULL restarts the cycle of images (in other words, a return of NULL signals the end of a cycle).

Parameters

filename.....Specifies the name of the test matrix file to use. If filename is NULL, then the default test matrix file xilch_tests is used.

`ts_get_complex_roi`

XilRoi ts_get_complex_roi (int xsize, int ysize);

Description

ts_get_complex_roi returns a ROI object. After you have finished using the ROI, use the XIL function xil_roi_destroy() to delete the ROI.

Parameters

xsize and ysize Dimensions of the image to which you want to attach the ROI.

`ts_destroy`

int ts_destroy (XilImage im);

Description Use this function to destroy any image created by the Test Suite library, because it also destroys the parent image if the passed image is a child image. If it is successful, ts_destroy() returns TS_SUCCESS. Otherwise, it returns TS_FAILURE.

Parameters

im.......Name of the image to destroy.

`ts_display`

void ts_display (XilImage im);

Description This function displays the image specified.

Parameters

im.......Name of the image to display.

Lookup Table Functions

`ts_lookup_verify`

int ts_lookup_verify (char *funcname, char *comment,
XilLookup lut, float tolerance, char *ref_name);

Description

ts_lookup_verify() verifies a lookup table (LUT) generated by the test program against the corresponding stored reference. It returns the number of differences it finds. This function is sensitive to the position of the entries in colormaps. In other words, if entry [i] in one colormap is BGR, then entry [i] in the other colormap must also be BGR. Otherwise, the function returns the differences resulting from entry position differences.

`ts_lookup_verify_contents`

int ts_lookup_verify_contents (char *funcname, char *comment,
XilLookup lut, float tolerance, char *ref_name)

Description

ts_lookup_verify_contents() verifies a lookup table (LUT) generated by the test program against the corresponding stored reference. It returns the number of differences it finds. This function is not sensitive to the position of the entries in colormaps. In other words, if entry [i] is BGR and entry [j] is bgr

in one colormap, and entry [i] is bgr and entry [j] is BGR in the other colormap, and all other entries in the two colormaps match, then this function will not find any differences. ts_lookup_verify() would find differences in this case.

Parameters

*funcname*	A string containing the name of the function that generated the LUT to be verified.
*comment*	A string containing a comment written to the log file.
*lut*	The LUT to be verified.
*tolerance*	Specifies a tolerance to be used in the comparison. For an exact comparison, use a tolerance of 0.0.
*ref_name*	Specifies the reference name that the library uses. If *ref_name* is NULL, the library uses a default name. Explicit naming is useful when a variable number of verifications is performed within a single test case or when `ts_lookup_getref()` is used. *ref_name* must be unique within the test case.

The library assigns default reference names in the following way. The call to ts_start_ref() initializes the default reference name to "r.0." Each call to ts_*_verify() that has NULL specified as ref_name increments the default reference name. For example, the reference name used in the first call to ts_*_verify() that has NULL specified as ref_name is "r.1" and the second is "r.2." When you supply a reference name, you should not specify a default name. When Xilch runs in verbose mode, reference names are printed to the log file.

`ts_lookup_checksum`

unsigned int ts_lookup_checksum (XilLookup lut);

Description

ts_lookup_checksum() returns a 32-bit CRC code for a LUT. This function performs a checksum calculation. Unlike ts_lookup_contents_checksum(), it does not produce identical CRC codes for lookups that have the same entries but with different ordering. The orderings must be the same to get the same CRC codes. ts_lookup_checksum() corresponds to ts_lookup_verify().

Parameters

lut.......The LUT on which to perform a checksum calculation.

`ts_lookup_contents_checksum`

unsigned int ts_lookup_contents_checksum (XilLookup lut);

Description

ts_lookup_contents_checksum() returns a 32-bit CRC code for a LUT. This function sorts the lookup table specified and then performs a checksum calculation. It produces identical CRC codes for lookups that have the same entries but with different ordering. ts_lookup_contents_checksum() corresponds to ts_lookup_verify_contents().

Parameters

lut.......The LUT on which to perform a checksum calculation.

`ts_lookup_getref`

XilLookup ts_lookup_getref ();

Description

ts_lookup_getref() retrieves reference data, if any. It returns NULL if there is no reference data. The reference data it retrieves is the data named by the current default reference name--the reference name used by the most recent call to ts_*_verify() in the current test case. See ts_verify() for an explanation of reference names. If you call ts_lookup_getref before calling ts_lookup_verify in the current test case, NULL is returned. You cannot call ts_lookup_getref outside a test case.

`ts_lookup_compare`

int ts_lookup_compare (XilLookup lut1, XilLookup lut2, float
tolerance);

Description

ts_lookup_compare() compares two lookup tables. It returns the number of differences it finds. This function is sensitive to the position of the entries in colormaps. In other words, if entry [i] in one colormap is BGR, then entry [i] in the other colormap must also be BGR. Otherwise, the function returns the differences resulting from entry position differences.

See also ts_lookup_compare_contents().

Parameters

*lut1* and *lut2*	The LUTs to compare.
*tolerance*	Specifies a tolerance to use in the comparison.

`ts_lookup_compare_contents`

int ts_lookup_compare_contents (XilLookup lut1, XilLookup
lut2, float tolerance);

Description

ts_lookup_compare_contents() compares two lookup tables. It returns the number of differences it finds. This function is not sensitive to the position of entries in colormaps. In other words, if entry [i] is BGR and entry [j] is bgr in one colormap, and entry [i] is bgr and entry [j] is BGR in the other colormap, and all other entries in the two colormaps match, then this function will not find any differences. ts_lookup_compare() would find differences in this case.

Parameters

*lut1* and *lut2*	The LUTs to compare.
*tolerance*	Specifies a tolerance to use in the comparison.

`ts_lookup_load`

XilLookup ts_lookup_load (char *filename);

Description

ts_lookup_load() loads the lookup table (LUT) from a file and returns a handle to that LUT if it is successful. Otherwise, it returns NULL.

Parameters

filename.....The name of the file from which ts_lookup_load() loads the LUT.

`ts_lookup_save`

int ts_lookup_save (XilLookup lut, char *filename);

Description

ts_lookup_save() saves a lookup table into a file. If this function runs successfully, it returns the value 1. Otherwise, it returns the value 0 (zero).

Parameters

*lut*	The name of the lookup table being saved.
*filename*	The name of the file into which `ts_lookup_save()` saves the LUT.

CIS Functions

`ts_cis_verify`

int ts_cis_verify (char *funcname, char *comment, XilCis cis,
float tolerance, char *ref_name);

Description

ts_cis_verify() verifies a compressed image sequence (CIS) generated by the test program against the corresponding stored reference. This function returns the number of differences it finds.

Parameters

*funcname*	A string containing the name of the function that generated the CIS to verify.
*comment*	A string containing a comment written to the log file if verbose mode is on. It can be NULL.
*cis*	The CIS to verify.
*tolerance*	Specifies a tolerance to use in the comparison.

ref_name....Specifies the reference name that the library uses. If ref_name is NULL, the library uses a default name. Explicit naming is useful when a variable number of verifications is performed within a single test case or when ts_cis_getref() is used. ref_name must be unique within the test case.

`ts_cis_getref`

XilCis ts_cis_getref ();

Description

ts_cis_getref() retrieves the named reference data, if any. It returns NULL if there is no reference data. The reference data it retrieves is the data named by the current default reference name--the reference name used by the most recent call to ts_*_verify() in the current test case. See ts_verify() for an explanation of reference names. If you call ts_cis_getref() before calling ts_cis_verify() in the current test case, NULL is returned. You cannot call ts_cis_getref() outside a test case.

`ts_cis_compare`

int ts_cis_compare (XilCis cis1, XilCis cis2, float tolerance);

Description

ts_cis_compare() compares two CISs. This function returns the number of differences it finds.

Parameters

*cis1* and *cis2*	The CISs to be compared.
*tolerance*	Specifies a tolerance to be used in the comparison.

`ts_cis_checksum`

unsigned int ts_cis_checksum (XilCis cis);

Description

ts_cis_checksum() returns a 32-bit CRC code for a CIS.

Parameters

cis.......The CIS on which to perform a checksum calculation.

`ts_cis_load`

XilCis ts_cis_load (char *cis_type, char *filename, int partial,
int copy, int nbytes);

Description

ts_cis_load() loads the compressed image sequence (CIS) from a file and returns a handle to that CIS if successful. Otherwise, it returns NULL.

Parameters

*cis_type*	A string that describes the type of compression, for example, "Mpeg1" or "JpegLL."
*filename*	The name of the file from which `ts_cis_load()` loads the CIS.
*partial*	Indicates that there are partial frames in the bitstream.
*copy*	Loads a copy of the CIS when the value is `1`. When the value is `0` (zero), it returns a pointer to the CIS.
*nbytes*	Specifies the number of bytes the function loads. This parameter needs to be specified only if the function is loading partial bitstreams.

`ts_cis_save`

int ts_cis_save (XilCis cis, char *filename);

Description

ts_cis_save saves the compressed image sequence (CIS) into a file. If this function runs successfully, it returns the value 1. Otherwise, it returns the value 0 (zero). If ts_cis_save() runs when verbose mode is on, it prints the number of frames and number of bytes it saved.

Parameters

*cis*	The CIS to save.
*filename*	The name of the file into which `ts_cis_save()` saves the CIS.

`ts_cis_destroy`

int ts_cis_destroy (XilCis cis)

Description

ts_cis_destroy() destroys a CIS. You should use this function only to destroy a CIS that was created by ts_cis_load(). If this function runs successfully, it returns the value 1. Otherwise, it returns the value 0 (zero).

Parameters

cis.......The CIS to destroy.

Float and Integer Functions

`ts_float_verify`

int ts_float_verify (char *funcname, char *comment,
float *fvec, int vecsize, float tolerance, char *ref_name);

Description

ts_float_verify() verifies a floating point vector generated by the test program against the corresponding stored reference. This function returns the number of differences it finds.

Parameters

*funcname*	A string containing the name of the function that generated the floating point vector to verify.
*comment*	A string containing a comment written to the log file if verbose mode is on. It can be NULL.
*fvec*	A pointer to the floating point vector to be verified.

*vecsize*	The size of the floating point vector.
*tolerance*	Specifies a tolerance to use in the comparison.
*ref_name*	Specifies the reference name that the library will use. If *ref_name* is NULL, the library uses a default name. Explicit naming is useful when a variable number of verifications is performed within a single test case or when `ts_float_getref()` is used. *ref_name* must be unique within the test case.

`ts_float_getref`

float *ts_float_getref (unsigned int *);

Description

ts_float_getref() returns the number of items in the array of the unsigned int argument pointer. You cannot call ts_float_getref() outside a test case.

`ts_float_load`

float *ts_float_load (char *filename, unsigned int *nvalues);

Description

ts_float_load() loads a floating point vector from a file and returns a pointer to the float if successful. Otherwise, it returns NULL.

Parameters

*filename*	The name of the file from which `ts_float_load()` loads the floating point vector.
*nvalues*	The number of values in the vector.

`ts_float_save`

int ts_float_save (float *vector, unsigned int nvalues,
char *filename);

Description

ts_float_save() saves a floating point vector into a file. If this function runs successfully, it returns the value 1; otherwise, it returns the value 0 (zero).

Parameters

*vector*	A pointer to the floating point vector.
*nvalues*	The number of values in the vector.
*filename*	The name of the file into which `ts_float_save()` saves the floating point vector.

`ts_int_verify`

int ts_int_verify (char *funcname, char *comment, int *ivec,
int vecsize, float tolerance, char *ref_name);

Description

ts_int_verify() verifies an integer vector generated by the test program against the corresponding stored reference. This function returns the number of differences it finds.

Parameters

*funcname*	A string containing the name of the function that generated the integer vector to be verified.
*comment*	A string containing a comment written to the log file if verbose mode is on. It can be NULL.
*ivec*	A pointer to the integer vector to be verified.
*vecsize*	The size of the integer vector.
*tolerance*	Specifies a tolerance to be used in the comparison.
*ref_name*	Specifies the reference name that the library will use. If *ref_name* is NULL, the library uses a default name. Explicit naming is useful when a variable number of verifications is performed within a single test case or when `ts_int_getref()` is used. *ref_name* must be unique within the test case.

`ts_int_getref`

int *ts_int_getref (unsigned int *);

Description

ts_int_getref() returns the number of items in the array of the unsigned int argument pointer. You cannot call ts_int_getref() outside a test case.

`ts_int_load`

int *ts_int_load (char *filename, unsigned int *nvalues);

Description

ts_int_load() loads an integer vector from a file and returns a pointer to the int if successful. Otherwise, it returns NULL.

Parameters

*filename*	The name of the file into which `ts_int_load()` loads the integer vector.
*nvalues*	The number of values in the integer vector.

`ts_int_save`

int ts_int_save (int *vector, unsigned int nvalues,
char *filename);

Description

ts_int_save() saves an integer vector into a file. If this function runs successfully, it returns the value 1; otherwise, it returns the value 0 (zero).

Parameters

*vector*	A pointer to the integer vector.
*nvalues*	The number of values in the integer vector.
*filename*	The name of the file into which `ts_int_save()` saves the integer vector.

Equivalence Testing Functions

`ts_child_check`

int ts_child_check (char *comment, FUNCFORMAT *format_list,
int operation_count, float tol, Display *display);

Description

ts_child_check() tests the behavior of a child image. The behavior is tested by producing a reference result and a test result and then comparing the test and reference results. A reference result is produced by performing the given operations on specified images. A test result is produced by performing the given operations on src and dst images, which are equivalent to the given images except that they are children of parent images.

Note - The test result should be exactly the same as the reference result.

This function returns the number of errors found. 0 (zero) is returned if the test succeeds. This function cannot be used with xil_lookup_convert, xil_histogram, and xil_compress.

Parameters

comment

A string containing a comment written to the log file if verbose mode is on. It can be NULL.

format_list

An operation list and can contain more than one operation. Child images are created for the source images of the first operation and for the destination image of the last operation. Other elements of the format list are not used. Comparisons are based on the results of the last operation. xil_decompress can be used only as the first operation in the format_list. See Appendix C, "Equivalence Testing Example," for an explanation of format lists.

*operation_count*	The number of items in the format list.
*tol*	The tolerance for comparison. Normally 0.0 is specified, except for molecule testing.
*display*	A pointer to a structure that is returned when you initially connect to the X server. If a value is specified for *display, a window is created in which the destination child testing is performed. If `NULL` is specified for display*, this function uses a memory image instead.

`ts_roi_check`

int ts_roi_check (char *comment, FUNCFORMAT *format_list,
int operation_count, float tol);

Description

ts_roi_check() tests the behavior of a ROI. The behavior is tested by producing a reference result and comparing this result with the ROI. This function cannot be used with xil_lookup_convert,

xil_choose_colormap, xil_squeeze_range, xil_histogram,
xil_compress, or xil_extrema.

Parameters

*comment*	A string containing a comment written to the log file if verbose mode is on. It can be NULL.
*format_list*	An operation list and can contain more than one operation. This is for testing molecules. The ROI is placed onto the source images of the first operation and the destination image of the last operation. Other elements of the format list are not used. Comparisons are based on the results of the last operation.

xil_decompress can be used only as the first operation in the format_list. See Appendix C, "Equivalence Testing Example," for an explanation of format lists.

*operation_count*	The number of items in the format list.
*tol*	The tolerance for comparison. Normally 0.0 is specified, except for molecule testing.

`ts_automatic_tests`

int ts_automatic_tests (char *comment, FUNCFORMAT *format_list,
int operation_count, float tol, Display *display);

Description

ts_automatic_test() calls all of the equivalence testing functions (ts_child_check() and ts_roi_check()) if you invoked Xilch with either the -test_signatures or -test_data option. This function returns the total of all of the pixels that differ in all of the automated tests. Equivalence tests do not modify any of the image arguments.

Parameters

*comment*	A string containing a comment written to the log file if verbose mode is on. It can be NULL.
*format_list*	An operation list, which can contain more than one operation. See Appendix C, "Equivalence Testing Example," for an explanation of format lists.
*operation_count*	The number of items in the format list.
*tol*	The tolerance for comparison. Normally 0.0 is specified, except for molecule testing.
*display*	A pointer to a structure that is returned when you initially connect to the X server. If a value is specified for *display, a window is created in which the destination child testing is performed. If `NULL` is specified for display*, this function uses a memory image instead.

Contained Within

Find More Documentation

Featured Support Resources

Writing Test Programs in the XIL Test Suite Environment

3

Example Test Program

Available XIL Test Suite Library Functions

Other Useful Examples

After You Write Your Test Program

Writing and Using Benchmarking Programs

Running Your Benchmarking Program

Using Equivalence Testing Functions

The Test Suite Library

Include Files

General Functions

ts_init

ts_end

ts_benchmark_start

ts_benchmark_end

ts_expect_errors

ts_log

ts_start_test_case

ts_end_test_case

Image Functions

ts_verify

ts_getref

ts_compare

ts_image_gen

ts_load

ts_save

ts_checksum

ts_get_src[123]_image and ts_get_dst[123]_image

ts_get_complex_roi

ts_destroy

ts_display

Lookup Table Functions

ts_lookup_verify

ts_lookup_verify_contents

ts_lookup_checksum

ts_lookup_contents_checksum

ts_lookup_getref

ts_lookup_compare

ts_lookup_compare_contents

ts_lookup_load

ts_lookup_save

CIS Functions

ts_cis_verify

ts_cis_getref

ts_cis_compare

ts_cis_checksum

ts_cis_load

ts_cis_save

ts_cis_destroy

Float and Integer Functions

ts_float_verify

ts_float_getref

ts_float_load

ts_float_save

ts_int_verify

ts_int_getref

ts_int_load

ts_int_save

Equivalence Testing Functions

ts_child_check

ts_roi_check

ts_automatic_tests

`ts_init`

`ts_end`

`ts_benchmark_start`

`ts_benchmark_end`

`ts_expect_errors`

`ts_log`

`ts_start_test_case`

`ts_end_test_case`

`ts_verify`

`ts_getref`

`ts_compare`

`ts_image_gen`

`ts_load`

`ts_save`

`ts_checksum`

`ts_get_src[123]_image` and `ts_get_dst[123]_image`

`ts_get_complex_roi`

`ts_destroy`

`ts_display`

`ts_lookup_verify`

`ts_lookup_verify_contents`

`ts_lookup_checksum`

`ts_lookup_contents_checksum`

`ts_lookup_getref`

`ts_lookup_compare`

`ts_lookup_compare_contents`

`ts_lookup_load`

`ts_lookup_save`

`ts_cis_verify`

`ts_cis_getref`

`ts_cis_compare`

`ts_cis_checksum`

`ts_cis_load`

`ts_cis_save`

`ts_cis_destroy`

`ts_float_verify`

`ts_float_getref`

`ts_float_load`

`ts_float_save`

`ts_int_verify`

`ts_int_getref`

`ts_int_load`

`ts_int_save`

`ts_child_check`

`ts_roi_check`

`ts_automatic_tests`