Skip to content

Mart Configurtion

I. Specifying the mutation scope (source files and functions to mutate)

The scope configuration file is a JSON file where the source files and functions to mutate can be specified in two list. The template is the following:

{
    "Source-Files": [<function1>, <function2>,...],
    "Functions": [<src_file1>, <src_file2>,...]
}

Not specifying mutation scope will mean nutating the whole LLVM bitcode module.

II. Specifying Mutants operators

Teh mutation operators to be applied may be specified using a simple description language. The Specification of the language follows.

1. Syntax Diagram

sample

The above Diagram represent the Syntax Diagram of the Mutation operator description language. The Bottom diagram is the representation of both the Matched Fragment and the Compatible Replacement Fragment.
Note: The argument (@, C, V, A, P) for the Compatible Replacing Fragment must be subset of those specified for the corresponding Matched Fragment.

Following is an example of mutation operators configuration:

ADD(@1,@2) --> Mutop1.1, SUB(@1, @2); Mutop1.2, SUB(@2, @1); Mutop1.3 TRAPSTMT;
LEFTINC(V) --> Mutop2.1, RIGHTDEC(V); Mutop2.2, ASSIGN(V, 0)

In this example we have 3 mutation operators:

  • Mutop1.1: Replace Sum of two expressions by Their Difference.

  • Mutop1.2: Replace Sum of two expressions by The negation of their difference Difference.

  • Mutop1.3: Replace Statement having a Sum by a Trap Statement (Failure).

  • Mutop2.1: Replace Variable left increment by its right decrement.

  • Mutop2.2: Replace Variable left increment by an assignement of 0 to it.

The currently Supported Fragment Elements are listed bellow.

2. Fragment Elements

The following table gives information about the currently Supported Fragment Elements (The Fragment Element names are case insensitive).

Fragment Element Description Matching Fragment Replacing Fragment Fragment Argument
@ Any Scalar Expression ✓ ✗ ✓
C Any Constant ✓ ✗ ✓
V Any Scalar Variable ✓ ✗ ✓
A Any Address ✓ ✗ ✓
P Any Pointer Variable ✓ ✗ ✓
CONSTVAL specific constant value: 1 arg (const val) ✗ ✓ ✗
OPERAND return an operand of an expression: 1 arg (operand class) ✗ ✓ ✗
ABS Absolute value of the argument (single argument) ✗ ✓ ✗
NEG Scalar arithmetic negation ✓ ✓ ✗
ADD Sum of two values ✓ ✓ ✗
SUB Scalar substraction: 2 args (left value, right value) ✓ ✓ ✗
MUL scalar multiplication: 2 args ✓ ✓ ✗
DIV Scalar division: 2 args (numerator, denominator) ✓ ✓ ✗
MOD scalar modulo operation: 2 args (left expr, right expr) ✓ ✓ ✗
BITAND Bit level and :2 args ✓ ✓ ✗
BITNOT bit level not :1 arg ✓ ✓ ✗
BITOR bit level or :2 args ✓ ✓ ✗
BITSHL bit level shift left :2 args (val, shift) ✓ ✓ ✗
BITSHR bit level shift right: 2 args (val, shift) ✓ ✓ ✗
BITXOR bit level xor: 2 args (val, shift) ✓ ✓ ✗
LEFTDEC Scalar left hand decrement: 1 arg (var) ✓ ✓ ✗
LEFTINC Scalar left hand increment: 1 arg (var) ✓ ✓ ✗
RIGHTDEC Scalar variable right decrement: 1 arg (var)) ✓ ✓ ✗
RIGHTINC Scalar variable right decrement: 1 arg (var)) ✓ ✓ ✗
EQ relational equal: 2 args (left expr, right expr) ✓ ✓ ✗
NEQ relational not equal: 2 args (left expr, right expr) ✓ ✓ ✗
GE relational greater or equal: 2 args (left expr, right expr) ✓ ✓ ✗
GT relational greater than: 2 args (left expr, right expr) ✓ ✓ ✗
LE relational less or equal: 2 args (left expr, right expr) ✓ ✓ ✗
LT relational less than: 2 args (left expr, right expr) ✓ ✓ ✗
AND Logical conjunction ✓ ✓ ✗
OR Logical or: 2 args (left expr, right expr)) ✓ ✓ ✗
ASSIGN variable assignement: 2 args (var, expr) ✓ ✓ ✗
PADD Address addition operation with integer: 2 args (address, integer) ✓ ✓ ✗
PSUB Address substraction operation with integer: 2 args (address, integer) ✓ ✓ ✗
PLEFTDEC Pointer variable left decrement: 1 arg (pointer variable) ✓ ✓ ✗
PLEFTINC Pointer variable left increment: 1 arg (pointer variable) ✓ ✓ ✗
PRIGHTDEC Pointer variable right decrement: 1 arg (pointer variable) ✓ ✓ ✗
PRIGHTINC Pointer variable right increment: 1 arg (pointer variable) ✓ ✓ ✗
PEQ Address relational equal operation: 2 args (left addr, right addr) ✓ ✓ ✗
PNEQ Address relational not equal operation ✓ ✓ ✗
PGE Address relational greater or equal operation: 2 args (left addr, right addr) ✓ ✓ ✗
PGT Address relational greater than operation: 2 args (left addr, right addr) ✓ ✓ ✗
PLE Address relational less or equal operation: 2 args (left addr, right addr) ✓ ✓ ✗
PLT Address relational less than operation ✓ ✓ ✗
PADD_DEREF Pointer-int addition followerd by dereference.e.g. *(p+3): 2 args (addess, int) ✓ ✓ ✗
PSUB_DEREF Address-int substraction followed by dereference.e.g. *(p-3): 2 args (Address, int) ✓ ✓ ✗
PDEREF_ADD Pointer dereference followed by addition.e.g. (*p)+2: 2 args (address, number) ✓ ✓ ✗
PDEREF_SUB Pointer dereference followed by substraction.e.g. (*p)-2: 2 args (address, number) ✓ ✓ ✗
PLEFTDEC_DEREF Pointer variable left decrement followed by dereference.e.g. *(--p): 1 args (pointer variable) ✓ ✓ ✗
PLEFTINC_DEREF Pointer variable left increment followed by dereference.e.g. *(--p): 1 args (pointer variable) ✓ ✓ ✗
PRIGHTDEC_DEREF Pointer variable right decrement followed by dereference.e.g. *(p--): 1 args (pointer variable) ✓ ✓ ✗
PRIGHTINC_DEREF Pointer variable right increment followed by dereference.e.g. *(p++): 1 args (pointer variable) ✓ ✓ ✗
PDEREF_LEFTDEC Pointer dereference followed by left decrement.e.g. --(*p): 1 args (pointer variable) ✓ ✓ ✗
PDEREF_LEFTINC Pointer dereference followed by left increment.e.g. ++(*p): 1 args (pointer variable) ✓ ✓ ✗
PDEREF_RIGHTDEC Pointer dereference followed by right decrement.e.g. (*p)--: 1 args (pointer variable) ✓ ✓ ✗
PDEREF_RIGHTINC Pointer dereference followed by right increment.e.g. (*p)++: 1 args (pointer variable) ✓ ✓ ✗
CALL function call: 1 arg (callee) ✓ ✗ ✗
NEWCALLEE Set new callee of function call: 1 arg (new callee) ✗ ✓ ✗
SHUFFLEARGS Shuffle the arguments of a function call: 1 arg (number of args to shuffle) ✗ ✓ ✗
SWITCH Match the a statement: no arg ✓ ✗ ✗
SHUFFLECASESDESTS Shuffle the destination BBs of a switch: 1 arg (number of destination BB to shuffle) ✗ ✓ ✗
REMOVECASES Remove a specific number of cases for switch instruction randomly: 1 args (number of cases to remove) ✗ ✓ ✗
RETURN_BREAK_CONTINUE match return, break or continue: no arg ✓ ✗ ✗
STMT Match any statement ✓ ✗ ✗
DELSTMT remove statement: no args ✗ ✓ ✗
TRAPSTMT a trap statement (artificial failure): no arg ✗ ✓ ✗

3. Programmatically Generate Mutants Operators Configuration

In order to programmatically create the mutant operators configuration file, there is a helper python script, located in <path to build dir>/tools/useful/create_mconf.py, that implement a class named GlobalDefs.

The objects of the class GlobalDefs have the following iportant properties:

1) FORMATS: Is a key value (python dict) of each relevant Fragment element as key, and the key's value is the fragment element's operands as list of operand classes.

2) RULES: Is a key value (python dict) of each relevant Fragment element as key, and the key's value is the list of compatible fragment element (that can replace this).

3) CLASSES: Define Fragment elements groups. This is a key value (python dict) having as key, each fragment element and as value the corresponding operator groups. Group granularity is represented by different levels separated by the character '/', similarly to the file system path structure on UNIX systems. e.g. 'EXPRESSION-MUTATION/SCALAR/BINARY/AO' is used for Arithmetic binary operations such as '+', '-', '', '/' as these form the same group. Nevertheless, '>', '<' are 'EXPRESSION-MUTATION/SCALAR/BINARY/RO' as they are relational binary operations (Note the common prefix). Thus '+', '-', '', '/', '>', '<' belong to the same group 'EXPRESSION-MUTATION/SCALAR/BINARY' for this group granularity.