Table of Contents

Scripting interface

Workcraft supports scripting using JavaScript language. Two modes of script execution are supported:

For batch mode it is often convenient to start Workcraft without GUI and without reading/writing configuration files. This is achieved by using -nogui and -noconfig command line parameter as follows (We presume that Workcraft home is in the search PATH and the platform-specific .sh/.bat extension of Workcraft runner is omitted): 

workcraft -nogui -noconfig -exec:'/path/to/script.js'

If a script contains file operation commands, such as loading work files or exporting the models, then all the file names in these commands are relative to the working directory. By default this coincides with Workcraft home, however, an alternative working directory can be passed after the -dir: command line parameter, as follows: 

workcraft -nogui -noconfig -exec:script.js -dir:'/working/directory/path/'

since v3.2.3 For a short JavaScript snippet, it may be more convenient to pass it directly in the command line: 

workcraft -nogui -exec:'print("Hello!");exit();'

For more information about these and other Workcraft startup options see Command line interface document.

Functions and variables

Here is a list of predefined wrapper functions, partitioned into categories, and global variables available for scripting.

Help

Text output

Note that conventional Java print functions can be also used, e.g. if you need to output text without adding a newline:

GUI and exit

Global variables

Workspace functions

File operations

Configuration

Config variables are saved in config.xml file (located under ~/.config/workcraft/ in Linux or ~\AppData\Roaming\workcraft\ in Windows). The variable name you pass to setConfigVar/getConfigVar functions can be derived from config.xml file and should include its dot-separated path in the XML tree. For example, setConfigVar("CircuitSettings.clearPin", "RN"); sets the variable clearPin under CircuitSettings group to a string RN.

Command execution

Model specific commands

Commands for conversion, transformation and verification of specific models.

Conversion commands

These commands are applied to the given work of a specific model type and produce a new model work.

Composition commands

These commands are applied to a set of STG works passed as a space-separated list of file names relative to the working directory, and produce a new STG work.

Statistics commands

These commands produce a statistics string for the given work of a specific model type.

Synthesis commands

These commands are applied to the given work of a specific model type and return a new model work.

Layout commands

These commands modify the given work of a specific model type.

Verification commands

These commands are applied to the given work of a specific model type and return a Boolean outcome of the check.

Note that the result of verification commands is of object Boolean type (with capital B), as opposed to primitive boolean type (with small b). In addition to the conventional true and false values, Boolean may also evaluate to null (e.g. when verification command is not applicable to the supplied model).

Care should be taken when handling Boolean values in JavaScript – they cannot be directly used in logic expressions. For example, consider function 'f()' that returns a Boolean.

The following code snippet would always print pass, because the Boolean value is implicitly converted into a non-empty string ("true", "false" or "null"), which always evaluates to boolean true: 

if (f()) print("pass"); else print("fail");  // PROBLEM: this always prints pass

Instead, an explicit comparison to the expected boolean value should be used, thus forcing the cast of Boolean into boolean (instead of string) for subsequent comparison: 

if (f() == true) print("pass"); else print("fail");

A cleaner way to encode logic expressions is to explicitly convert the value into boolean by using booleanValue() method of Boolean type (this code would throw an exception if the result of f() is not Boolean or the returned value is null): 

if (f().booleanValue()) print("pass"); else print("fail");

Transformation commands

These commands modify the given work of a specific model type.

Cross-reference commands

These commands are intended for cross-referencing between work files.

Script examples

Basic

stg-transform.js
// Mirror signals and untoggle transitions of STG model
inStgWork = load("in.stg.work");
transformStgMirrorSignal(inStgWork);
outStgWork = convertStgUntoggle(inStgWork);
save(outStgWork, "out.stg.work");
exit();
buck-synth.js
// Complex gate implementation for basic buck controller
stgWork = load("buck.stg.work");
circuitWork = synthComplexGatePetrify(stgWork);
save(circuitWork, "buck.circuit.work");
exportVerilog(circuitWork, "buck.v");
exit();
workspace-info.js
// Print info for each loaded work and convert its title to upper case
for each (work in getWorks()) {
    title = work.getTitle();
    print("Info for " + title);
    print("  * Descriptor: " + getModelDescriptor(work));
    print("  * File: " + getWorkFile(work).getName());
    setModelTitle(work, title.toUpperCase());
    print("  * Title: " + getModelTitle(work);
}

Advanced

synth.js
// Technology mapping of the specified .g files whose names are passed
// without extension, as follows:
// workcraft -dir:WORKING_DIRECTORY_PATH -exec:synth.js TEST1 TEST2
setConfigVar("CircuitSettings.gateLibrary", "path-to-genlib-file");
for each (name in args) {
    stgWork = import(name + ".g");
    if (stgWork == null) {
        eprint("STG work loading failed!");
        exit();
    }
    if (checkStgCsc(stgWork) == true) {
        cscStgWork = stgWork;
    } else {
        cscStgWork = resolveCscConflictPetrify(stgWork);
        if (cscStgWork == null) {
            eprint("CSC conflict resolution failed!");
            exit();
        }
        save(cscStgWork, "vme-csc.stg.work");
    }
    tmCircuitWork = synthTechnologyMappingMpsat(cscStgWork);
    if (tmCircuitWork == null) {
        eprint("Circuit synthesis failed!");
        exit();
    }
    if (checkCircuitCombined(tmCircuitWork) == true) {
        exportVerilog(tmCircuitWork, name + ".v");
    } else {
        eprint("Circuit verification failed!");
    }
}
exit();
reset.js
// Define circuit initialisation scheme and insert active-low reset
// (requires Workcraft v3.2.3 or newer)
work = load("test-tm.circuit.work");
if (checkCircuitCombined(work) != true) {
    eprint("Circuit verification failed");
    exit();
}
tagCircuitForcedInitClearAll(work);
tagCircuitForcedInitInputPorts(work);
tagCircuitForcedInitAutoAppend(work);
insertCircuitResetActiveLow(work);
if (checkCircuitReset(work) != true) {
    eprint("Circuit cannot be reset to the required initial state");
    exit();
}
if (checkCircuitCombined(work) != true) {
    eprint("Circuit verification failed after reset insertion");
    exit();
}
exportVerilog(work, "test-tm-reset.v");
exit();