checkasm.h File Reference

Detailed Description

Main checkasm API for test suite configuration and execution.

This header provides the primary checkasm API for setting up and running assembly test suites, including configuration structures, test registration, and benchmark execution. It defines the main entry points and configuration options for checkasm-based test programs.

Go to the source code of this file.

Data Structures
struct	CheckasmCpuInfo
	Describes a CPU feature flag/capability. More...
struct	CheckasmTest
	Describes a single test function. More...
struct	CheckasmConfig
	Configuration structure for the checkasm test suite. More...

Typedefs
typedef uint64_t	CheckasmCpu
	Opaque type representing a set of CPU feature flags.
typedef uintptr_t	CheckasmKey
	Opaque type used to identify function implementations.

Enumerations
enum	CheckasmFormat {   CHECKASM_FORMAT_PRETTY , CHECKASM_FORMAT_CSV , CHECKASM_FORMAT_TSV , CHECKASM_FORMAT_JSON ,   CHECKASM_FORMAT_HTML }
	Output format for benchmark results. More...

Functions
CHECKASM_API CheckasmCpu	checkasm_get_cpu_flags (void)
	Get the current active set of CPU flags.
CHECKASM_API void	checkasm_list_cpu_flags (const CheckasmConfig *config)
	Print available CPU flags to stdout.
CHECKASM_API void	checkasm_list_tests (const CheckasmConfig *config)
	Print available tests.
CHECKASM_API void	checkasm_list_functions (const CheckasmConfig *config)
	Print available functions within tests.
CHECKASM_API int	checkasm_run (const CheckasmConfig *config)
	Run all tests and benchmarks matching the specified patterns.
CHECKASM_API int	checkasm_main (CheckasmConfig *config, int argc, const char *argv[])
	Main entry point for checkasm test programs.

Typedef Documentation

CheckasmCpu

typedef uint64_t CheckasmCpu

Opaque type representing a set of CPU feature flags.

Bitfield type used to represent CPU capabilities and SIMD instruction set support. The specific bit values are defined by the implementation.

CheckasmKey

typedef uintptr_t CheckasmKey

Opaque type used to identify function implementations.

Used internally by checkasm to track and match different variants of functions being tested.

Enumeration Type Documentation

CheckasmFormat

enum CheckasmFormat

Output format for benchmark results.

Specifies how benchmark results should be formatted.

Note

In all cases, output is written to stdout by default.

Enumerator
CHECKASM_FORMAT_PRETTY	Pretty-printed (colored) text output (default)
CHECKASM_FORMAT_CSV	Comma-separated values with optional header
CHECKASM_FORMAT_TSV	Tab-separated values with optional header
CHECKASM_FORMAT_JSON	JSON structured output with all measurement data
CHECKASM_FORMAT_HTML	Interactive HTML report for web viewing

Function Documentation

checkasm_get_cpu_flags()

CHECKASM_API CheckasmCpu checkasm_get_cpu_flags

(

void

)

Get the current active set of CPU flags.

Returns the currently active (masked) set of CPU flags. During test execution, this reflects which CPU features are currently being tested. May be called from within test functions to choose an implementation to test.

Returns

Current CPU feature flags as a bitmask

Note

The returned value changes as checkasm iterates through different CPU feature sets during testing.

checkasm_list_cpu_flags()

CHECKASM_API void checkasm_list_cpu_flags

(

const CheckasmConfig *

config

)

Print available CPU flags to stdout.

Prints a list of all CPU flags/features that are available for testing based on the configuration, as well as CPU flags which are defined but unsupported on the system.

Parameters

[in]

config

Configuration containing CPU flag definitions

checkasm_list_functions()

CHECKASM_API void checkasm_list_functions

(

const CheckasmConfig *

config

)

Print available functions within tests.

Prints a detailed list of all functions being tested across all registered tests. Useful for discovering what can be filtered with function patterns.

Parameters

[in]

config

Configuration containing test definitions

Note

This requires executing all tests to gather information about the available functions. During this process, checkasm_check_func() always returns 0 to skip the actual testing. However, any side effects from test functions will still occur, unless properly guarded.

checkasm_list_tests()

CHECKASM_API void checkasm_list_tests

(

const CheckasmConfig *

config

)

Print available tests.

Prints a list of all test functions registered in the configuration. Useful for discovering what tests are available and for use with test pattern filtering.

Parameters

[in]

config

Configuration containing test definitions

checkasm_main()

CHECKASM_API int checkasm_main	(	CheckasmConfig *	config,
		int	argc,
		const char *	argv[] )

Main entry point for checkasm test programs.

Convenience wrapper around checkasm_run() that parses command-line arguments and updates the config accordingly. This is the recommended entry point for most checkasm test programs. Call this from your main() function.

Before calling this function, initialize config with the minimum set of project-specific fields:

• config.cpu_flags: Array of CPU features to test
• config.tests: Array of test functions
• config.cpu: Detected CPU capabilities

Command-line arguments like –bench, –test, –function, –seed, etc. are automatically parsed and applied to the config.

Parameters

[in,out]	config	Configuration structure (will be modified by argument parsing)
[in]	argc	Argument count from main()
[in]	argv	Argument vector from main()

Returns

0 on success, non-zero on failure (suitable for return from main())

int main(int argc, const char *argv[]) {
    CheckasmConfig config = {
        .cpu_flags     = my_cpu_flags,
        .tests         = my_tests,
        .cpu           = my_get_cpu_flags(),
        .set_cpu_flags = my_set_cpu_flags,
    };
    return checkasm_main(&config, argc, argv);
}

See also

checkasm_run()

checkasm_run()

CHECKASM_API int checkasm_run

(

const CheckasmConfig *

config

)

Run all tests and benchmarks matching the specified patterns.

Executes the checkasm test suite according to the configuration. Tests and functions are filtered according to test_pattern and function_pattern if specified. Benchmarks are run if bench is enabled.

Parameters

[in]

config

Configuration structure with all test parameters

Returns

0 on success (all tests passed), negative error code on failure

Note

This is the lower-level entry point. Most users should use checkasm_main() instead, which handles argument parsing.

See also

checkasm_main()