RUNSTAPL

The RUNSTAPL function is used to execute a STAPL or JAM(TM) file and return the result. After execution of the STAPL file, the JTAG chain is left undisturbed until XJTAG next accesses the JTAG chain.

The RUNSTAPL function cannot be used inside either a HOLDOFF block or a raw JTAG block.

The fourth parameter, options, can be omitted, but doing so is deprecated. A warning will be emitted and this ability will be removed in a future version.

RUNSTAPL( STRING filename, STRING action, STRING devices, INT options )

Action argument

The simplest action argument is the name of the action to run. In addition, STAPL variables and procedures may be overridden and STAPL engine parameters may be set. Each one is separated by a space.

" action [ variable = value | procedure = [0|1] ] ... "

The following example runs the action PROGRAM, sets the variable debug to 1 and disables the recommended procedure VERIFY:

"PROGRAM debug=1 VERIFY=0"

If any of the actions could not be found, then an error will be printed to the output and the XJEase execution will be stopped.

Syntax of devices

[boardName1.]deviceName1..[boardName2.]deviceName2
or
[boardName1.]deviceName1[,[boardNameN.]deviceNameN]

boardName is necessary if you have more than one device with the same name (e.g. IC1), on different boards. Otherwise, it is optional.

The STAPL file will be run only on the devices specified. Devices must be consecutive in the JTAG chain, but can be specified in any order.

If any of the devices are multicore devices then the name of the core must be specified as well:

[boardName.]deviceName.coreName

If the device range is constant, it will be checked at compile-time and if there is a syntax error or if any of the devices are not found or are ambiguous, an error is generated. However, if the string is not a constant (i.e. it is constructed from other arguments) it may not be possible to verify it at compile-time; instead an error will be displayed when the function is run and code execution will stop.

Options argument

There are two options available when running a STAPL file:

STAPL_AUTOSKEW

STAPL_AUTOSKEW controls what happens when the STAPL file changes the TCK frequency. The XJTAG system normally automatically compensates for skew in the JTAG signals by running a process known as AutoSkew. However, this procedure can affect the running of a STAPL file and therefore the user has the ability to enable or disable it.

In almost all cases this option should be enabled. In some limited circumstances, enabling this feature can cause the STAPL file to fail; in this case the option should still be enabled, however, the skew values can be pre-calculated using SETFREQ before the STAPL file is run. The system will remember and use these values when the TCK frequency is changed. This example shows a STAPL file that changes the TCK frequency to 15MHz and 30MHz:

// Set the TCK frequency to 15MHz and then 30MHz to precalculate the skew values for the STAPL file
JTAG
  SETFREQ(15 * 1000 * 1000);
  SETFREQ(30 * 1000 * 1000);
END;

// Now run the STAPL file with the STAPL_AUTOSKEW option
result := RUNSTAPL(staplFile, "PROGRAM", "IC2..IC3", STAPL_AUTOSKEW);

STAPL_RESET

STAPL_RESET controls what happens when the STAPL file has finished. A STAPL file may be used to configure a device or leave it in a specific state. When the STAPL file completes, if the STAPL_RESET option is set the XJTAG system resets the JTAG chain using either a TMS reset or a test-reset sequence if configured. Omitting this option will prevent the reset from being applied.

In the majority of cases this option should be enabled. However, if applying a reset will clear any configuration that the file has set, or if the subsequent XJEase code relies on the state that the file leaves the chain in, this option can be disabled.

If both options are required, then OR them together. If neither option is required then pass in a zero. It is possible to omit the options entirely, which is the same as passing in zero, but this is deprecated and will be removed in a future version.

Engine parameters

The STAPL engine has a fixed maximum instruction length, which is typically long enough for most STAPL files. However, there may be cases where the default of 5MB is too short, and so it is possible to override it by passing a value in the action argument. The parameter is set by assigning the value to the _max_instruction_length_ parameter:

// Override the maximum instruction length to ~10MB
result := RUNSTAPL(staplFile, "PROGRAM _max_instruction_length_=10000000", "IC2..IC3", STAPL_AUTOSKEW | STAPL_RESET);

Engine parameters have the leading and trailing underscores to avoid any possible collision with other STAPL variables.

Example

GLOBAL RunStaplProgrammingFile()(INT result)
  CONST STRING staplFile := "programming.stapl";

  PRINT("Programming STAPL File: ", staplFile, "\n");
  result := RUNSTAPL(staplFile, "PROGRAM", "IC2..IC3", STAPL_AUTOSKEW | STAPL_RESET);
  IF result != 0 THEN
    PRINT("STAPL Programming failed.\n");
  ELSE
    PRINT("STAPL Programming complete.\n");
  END;
END;

This will run the STAPL file on all devices in the JTAG chain from IC2 to IC3. AutoSkew will be applied whenever there is a change in the TCK frequency and the devices in the JTAG chain will be reset when the file finishes Other devices in the chain will be held in BYPASS.

Error Codes

Exit codes returned from the STAPL file

These are the codes that the specification lists, which STAPL files should use by convention. However, other values outside this set are possible.

Exit codes returned from the STAPL runner

These are some of the possible codes that the STAPL player can return and indicate some error in actually parsing or running the file.

Jam is a trademark of Altera Corporation.