User Tools

Site Tools


help:scripting

Scripting interface

Workcraft supports scripting using JavaScript language.

Modes of script execution

Two modes of script execution are supported:

  • Interactively, by entering the script commands in the Javascript tab and pressing Ctrl+Enter to execute them. The output of the commands is redirected to the Output tab.
  • In batch mode, by passing the script file name after the -exec: command line parameter.

For batch mode it is often convenient to start Workcraft without GUI, by using the -nogui 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 -exec:SCRIPT_FILE_NAME

Note that the script file name should include the path to the file, either absolute or relative to the Workcraft home directory (where workcraft starter script is located).

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 -exec:SCRIPT_FILE_NAME -dir:WORKING_DIRECTORY_PATH

In Bash shell, for a short JavaScript snippet, it may be more convenient to pass it directly in the command line, as a process substitution form of redirection:

workcraft -nogui -exec:<(echo 'JAVASCRIPT CODE')

Special symbols in file names

If you have to use a backslash symbol \ in your script, e.g. in a Windows file path, then do not forget to escape it. Also if the file path contains spaces or other suspicious symbols, then put this path in quotes in the command line.

For example, if you want to run a script “C:\Workcraft Projects\test1.js” that loads a model from “C:\Workcraft Projects\models\test1.work” and save its statistics in “C:\Temp\test1.txt”, then the Windows command line would look like this (notice the quotes around the paths with spaces):

workcraft.bat -dir:"C:\Workcraft Projects" -exec:"C:\Workcraft Projects\test1.js"

and the script would be as follows (notice the double backslashes):

test1.js
work = load("models\\test1.work");
stat = statModel(work);
write(stat, "C:\\Temp\\test1.txt");
exit();

Here the “models\test1.work” is relative to the working directory “C:\Workcraft Projects”, while the file “C:\Temp\test1.txt” is specified by its absolute path.

Functions and variables

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

Help

  • help(substring) – output all the helper functions whose name contains the given substring
  • apropos(substring) – output all the helper functions whose name or description contains the given substring
  • getHelp(substring, searchDescription) – return a string with all helper functions whose name contains the substring; if the searchDescription is true, then also search the function descriptions

Text output

  • print(msg) – output msg to stdout and add a newline
  • eprint(msg) – output msg to stderr and add a newline
  • write(text, fileName) – write text to a file fileName (relative to the working directory) or to stdout if fileName is skipped

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

  • System.out.print(text) – output text to stdout
  • System.err.print(text) – output text to stderr

GUI and exit

  • startGUI() – start GUI
  • stopGUI() – stop GUI and switch to console mode
  • quit() or exit() – exit Workcraft

Global variables

  • args – command line parameters passed to Workcraft; these can be iterated over as follows: for each (arg in args) {…}
  • framework – the Workcraft framework singleton
  • workspaceEntry – the current work
  • modelEntry – the current model entry, a shortcut to workspaceEntry.getModelEntry()
  • visualModel – the current visual model, a shortcut to modelEntry.getVisualModel()
  • mathModel – the current math model, a shortcut to modelEntry.getMathModel()

Workspace functions

  • getWorks() – return an iterable array of loaded works
  • getWorkFile(work) – return a file object for the specified work
  • getModelDescriptor(work) – return a model descriptor string for the specified work
  • getModelTitle(work) – return a model title string for the specified work
  • setModelTitle(work, title) – set the model title of the specified work to the title string

File operations

  • load(fileName) – load a model from the given work file fileName and return its work
  • import(fileName) – import a model from the given file fileName and return its work; the model type is determined by the fileName extension:
    • .gASTG file for a STG model
    • .sgASTG file for a FST model
    • .vVerilog netlist file for a circuit model
  • save(work, fileName) – save the specified work into a file with the given fileName
  • exportSvg(work, fileName) – export the specified work as a Scalable Vector Graphics (*.svg) with the given fileName
  • exportPng(work, fileName) – export the specified work as a Portable Network Graphics (*.png) with the given fileName
  • exportPdf(work, fileName) – export the specified work as a Portable Document Format (*.pdf) with the given fileName
  • exportPs(work, fileName) – export the specified work as a PostScript (*.ps) with the given fileName
  • exportEps(work, fileName) – export the specified work as an Encapsulated PostScript (*.eps) with the given fileName
  • exportDot(work, fileName) – export the specified work as a GraphViz (*.dot) with the given fileName
  • exportStgG(work, fileName) – export the specified STG work as a Signal Transition Graph (*.g) with the given fileName
  • exportStgLpn(work, fileName) – export the specified STG work as a Labelled Petri Net (*.lpn) with the given fileName
  • exportFstSg(work, fileName) – export the specified FST work as a State Graph (*.sg) with the given fileName
  • exportCircuitVerilog(work, fileName) – export the specified Circuit work as a Verilog netlist (*.v) with the given fileName
  • exportDfsVerilog(work, fileName) – export the specified DFS work as a Verilog netlist (*.v) fileName

Configuration

  • setConfigVar(key, val) – set the config variable key to value val
  • getConfigVar(key) – return the value of config variable key
  • saveConfig() – save settings into the default config file
  • loadConfig() – load settings from the default config file

Command execution

  • execFile(fileName) – execute JavaScript with the given fileName
  • runCommand(work, className) – apply the command className to the specified work as a background task
  • executeCommand(work, className) – apply the command className to the specified work and wait for the result

Conversion commands -- applied to the given work and produce a new work

  • Conversion between different model types (sorted alphabetically)
    • convertCircuitToStg(work) – convert the given Circuit work into a new STG work
    • convertCircuitToStgWithEnvironment(work) – convert the given Circuit work and its environment into a new STG work
    • convertDfsToStg(work) – convert the given DFS work into a new STG work
    • convertFsmToFst(work) – convert the given FSM work into a new FST work
    • convertFsmToGraph(work) – convert the given FSM work into a new Graph work
    • convertFsmToPetri(work) – convert the given FSM work into a new Petri net work
    • convertFstToFsm(work) – convert the given FST work into a new FSM work
    • convertFstToStg(work) – convert the given FST work into a new STG work
    • convertGraphToFsm(work) – convert the given Graph work into a new FSM work
    • convertGraphToPetri(work) – convert the given Graph work into a new Petri net work
    • convertPetriToFsm(work) – convert the given Petri net work into a new FSM work
    • convertPetriToPolicy(work) – convert the given Petri net work into a new Policy net work
    • convertPetriToStg(work) – convert the given Petri net work into a new STG work
    • convertPolicyToPetri(work) – convert the given Policy net work into a new Petri net work
    • convertStgToBinaryFst(work) – convert the given STG work into a new binary FST work
    • convertStgToFst(work) – convert the given STG work into a new FST work
    • convertStgToPetri(work) – convert the given STG work into a new Petri net work
    • convertWtgToStg(work) – convert the given WTG work into a new STG work
  • Conversion of STG and Petri net models using net sysnthesis of Petrify
    • convertPetriSynthesis(work) – convert the given Petri net, STG, FSM or FST work into a new work using net synthesis
    • convertPetriSynthesisEr(work) – convert the given Petri net/FSM or STG/FST work into a new Petri net or STG work using net synthesis with a different label for each excitation region
    • convertPetriHideTransition(work) – convert the given Petri net or STG work into a new work hiding selected signals and dummies
    • convertPetriHideErTransition(work) – convert the given Petri net or STG work into a new Petri net or STG work hiding selected signals and dummies with a different label for each excitation region
    • convertStgUntoggle(work) – convert the given STG work into a new work where the selected (or all) transitions are untoggled
    • convertStgHideDummy(work) – convert the given STG work into a new work without dummies

Statistics commands -- produce a statistics string for the given work

  • statModel(work) – node and arc count for the model work (all model types are supported)
  • statPetri(work) – advanced complexity estimates for the Petri net work
  • statStg(work) – advanced complexity estimates for the STG work
  • statCircuit(work) – advanced complexity estimates for the Circuit work

Synthesis commands -- applied to the given work and return a new work

  • Logic synthesis of Circuits from STGs using Petrify backend
    • synthComplexGatePetrify(work) – logic synthesis of the given STG work into a complex gate Circuit work using Petrify backend
    • synthGeneralisedCelementPetrify(work) – synthesis of the given STG work into a generalised C-element Circuit using Petrify
    • synthStandardCelementPetrify(work) – synthesis of the given STG work into a standard C-element Circuit work using Petrify
    • synthTechnologyMappingPetrify(work) – technology mapping of the given STG work into a Circuit work using Petrify
  • Logic synthesis of Circuits from STGs using MPSat backend
    • synthComplexGateMpsat(work) – logic synthesis of the given STG work into a complex gate Circuit work using MPSat backend
    • synthGeneralisedCelementMpsat(work) – synthesis of the STG work into a generalised C-element Circuit work using MPSat
    • synthStandardCelementMpsat(work) – synthesis of the given STG work into a standard C-element Circuit work using MPSat
    • synthTechnologyMappingMpsat(work) – technology mapping of the given STG work into a Circuit work using MPSat

Layout commands -- modify the given work

  • layoutModelDot(work) – position nodes and shape the arcs using of the model work using Graphviz backend
  • layoutModelRandom(work) – randomly position graph nodes of the model work and connect them by straight arcs
  • layoutCircuit(work) – place components and route wires of the Circuit work
  • layoutCircuitPlacement(work) – place components of the Circuit work
  • layoutCircuitRouting(work) – route wires of the Circuit work

Verification commands -- applied to the given work and return a Boolean outcome of the check

  • Commands specific for Graph models
    • checkGraphReachability(work) – check the Graph work for reachability of all its nodes
  • Commands specific for FSM models (and derived models, e.g. FST)
    • checkFsmDeadlockFreeness(work) – check the FSM or FST work for deadlock freeness
    • checkFsmDeterminism(work) – check the FSM or FST work for determinism
    • checkFsmReachability(work) – check the FSM or FST work for reachability of all states
    • checkFsmReversibility(work) – check the FSM or FST work for reversibility of all states
  • Commands specific for Policy net models
    • checkPolicyDeadlockFreeness(work) – check the Policy net work for deadlock freeness
  • Commands specific for STG models
    • checkStgCombined(work) – combined check of the STG work for consistency, deadlock freeness, input properness and output persistency
    • checkStgConsistency(work) – check the STG work for consistency
    • checkStgDeadlockFreeness(work) – check the STG (or Petri net) work for deadlock freeness
    • checkStgInputProperness(work) – check the STG work for input properness
    • checkStgOutputPersistency(work) – check the STG work for output persistency
    • checkStgCsc(work) – check the STG work for CSC
    • checkStgUsc(work) – check the STG work for USC
    • checkStgDiInterface(work) – check the STG work for DI interface
    • checkStgNormalcy(work) – check the STG work for normalcy
    • checkStgMutexImplementability(work) – check the STG work for implementability of its mutex places
  • Commands specific for Circuit models
    • checkCircuitCombined(work) – combined check of the Circuit work for deadlock freeness, conformation to environment and output persistency
    • checkCircuitConformation(work) – check the Circuit work for conformation to environment
    • checkCircuitDeadlockFreeness(work) – check the Circuit work for deadlock freeness
    • checkCircuitOutputPersistency(work) – check the Circuit work for output persistency
    • checkCircuitStrictImplementation(work) – check the Circuit work for strict implementation of its signals according to the environment
  • Commands specific for DFS models
    • checkDfsCombined(work) – combined check of the DFS work for deadlock freeness and output persistency
    • checkDfsDeadlockFreeness(work) – check the DFS work for deadlock freeness
    • checkDfsOutputPersistency(work) – check the DFS work for output persistency

Transformation commands (modify the given work)

  • Generic commands applicable to all models
    • transformModelCopyLabel(work) – transform the given Model work by copying unique names of the selected (or all) nodes into their labels
    • transformModelStraightenConnection(work) – transform the given Model work by straightening selected (or all) arcs
  • Commands specific for FSM and derived models
    • transformFsmMergeState(work) – transform the given FSM or FST work by merging selected states
    • transformFsmContractState(work) – transform the given FSM or FST work by contracting selected states
  • Commands specific for Petri net and (if explicitly stated) for derived models
    • transformPetriContractTransition(work) – transform the given Petri net work by contracting a selected transition
    • transformPetriMergeTransition(work) – transform the given Petri net work by merging selected transitions
    • transformPetriDirectedArcToReadArc(work) – transform the given Petri net (or derived model, e.g.STG) work by converting selected arcs to read-arcs
    • transformPetriDualArcToReadArc(work) – transform the given Petri net (or derived model, e.g.STG) work by converting selected (or all) dual producing/consuming arcs to read-arcs
    • transformPetriReadArcToDualArc(work) – transform the given Petri net (or derived model, e.g.STG) work by converting selected (or all) read-arcs to dual producing/consuming arcs
    • transformPetriCollapseProxy(work) – transform the given Petri net (or derived model, e.g.STG) work by collapsing selected (or all) proxy places
    • transformPetriProxyDirectedArcPlace(work) – transform the given Petri net (or derived model, e.g.STG) work by creating proxies for selected producing/consuming arc places
    • transformPetriProxyReadArcPlace(work) – transform the given Petri net (or derived model, e.g.STG) work by creating selected (or all) proxies for read-arc places
    • transformPetriMergePlace(work) – transform the given Petri net (or derived model, e.g.STG) work by merging selected places
  • Commands specific for Policy net models
    • transformPolicyBundleTransition(work) – transform the given Policy net work by bundling selected transitions
  • Commands specific for STG models
    • transformStgMirrorSignal(work) – transform the given STG work by mirroring selected (or all) signals
    • transformStgMirrorTransition(work) – transform the given STG work by mirroring selected (or all) transition sign
    • transformStgImplicitPlace(work) – transform the given STG work by making selected (or all) places implicit
    • transformStgExplicitPlace(work) – transform the given STG work by making selected (or all) places explicit
    • transformStgSignalToDummyTransition(work) – transform the given STG work by converting selected signal transitions to dummies
    • transformStgDummyToSignalTransition(work) – transform the given STG work by converting selected dummies to signal transitions
    • transformStgContractNamedTransition(work) – transform the given STG work by contracting a selected transition
    • transformStgMergeTransition(work) – transform the given STG work by merging selected transitions
    • transformStgInsertDummy(work) – transform the given STG work by inserting dummies into selected arcs
    • transformStgExpandHandshake(work) – transform the given STG work by expanding selected handshake transitions
    • transformStgExpandHandshakeReqAck(work) – transform the given STG work by expanding selected handshake transitions by adding _req and _ack suffixes
  • Commands specific for Circuit models
    • transformCircuitContractJoint(work) – transform the given Circuit work by contracting selected (or all) joints
    • transformCircuitSplitJoint(work) – transform the given Circuit work by splitting selected (or all) joints
    • transformCircuitDetachJoint(work) – transform the given Circuit work by detaching selected (or all joints)
    • transformCircuitContractComponent(work) – transform the given Circuit work by contracting selected single-input/single-output components
    • transformCircuitInsertBuffer(work) – transform the given Circuit work by inserting buffers into selected wires
    • transformCircuitToggleBubble(work) – transform the given Circuit work by toggling inversion of selected contacts and outputs of selected components
  • Commands specific for DFS models
    • transformDfsMergeComponent(work) – transform the given DFS work by merging selected components
    • transformDfsContractComponent(work) – transform the given DFS work by contracting selected components
    • transformDfsWagging2Way(work) – transform the given DFS work by by applying 2-way wagging to the selected pipeline section
    • transformDfsWagging3Way(work) – transform the given DFS work by by applying 3-way wagging to the selected pipeline section
    • transformDfsWagging4Way(work) – transform the given DFS work by by applying 4-way wagging to the selected pipeline section

Script examples

Basic

stg-transform.js
// Mirror signals and untoggle transitions of STG model
inStgWork = load("in.stg.work");
transformStgMirrorSignal(inStg);
outStgWork = convertStgUntoggle(inStg);
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();

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();