Using the Command-Line Jam STAPL Solution for Device Programming
The Jam™ Standard Test and Programming Language (STAPL) standard is compatible with all Altera devices that supports in-system
programming (ISP) using JTAG. You can implement the Jam STAPL solution using the Jam STAPL players and the quartus_jli command-line executable.
You can simplify in-field upgrades and enhance the quality, flexibility, and life-cycle of your end products by using Jam
STAPL to implement ISP. The Jam STAPL solution provides a software-level and vendor-independent standard for ISP using PCs
or embedded processors. The Jam STAPL solution is suitable for embedded systems—small file size, ease of use, and platform
Jam STAPL Players
Altera supports two types of Jam STAPL file formats. There are two Jam STAPL players to accommodate these file types.
Jam STAPL Player—ASCII text-based Jam STAPL files (.jam)
Jam STAPL Byte-Code Player—byte-code Jam STAPL files (.jbc)
The Jam STAPL players parse the descriptive information in the .jam or .jbc. The players then interprets the information as data and algorithms to program the targeted devices. The players do not program
a particular vendor or device architecture but only read and understand the syntax defined by the Jam STAPL specification.
Alternatively, you can also use the quartus_jli command-line executable to program and test Altera® devices using .jam or .jbc. The quartus_jli command-line executable is provided with the Quartus® II software version 6.0 and later.
Differences Between the Jam STAPL Players and quartus_jli
A single .jam or .jbc can contain several functions such as programming, configuring, verifying, erasing, and blank-checking a device.
The Jam STAPL players are interpreter programs that read and execute the .jam or .jbc files. The Jam STAPL players can access the IEEE 1149.1 signals that are used for all instructions based on the IEEE 1149.1
interface. The players can also process user-specified actions and procedures in the .jam or .jbc.
The quartus_jli command-line executable has the same functionality as the Jam STAPL players but with additional capabilities:
It provides command-line control of the Quartus II software from the UNIX or DOS prompt.
It supports all programming hardware available in the Quartus II software version 6.0 and later.
Table 1. Differences Between Jam STAPL Players and quartus_jli Command-Line
You can download the Altera Jam STAPL players from the Altera website.
You can find the quartus_jli command-line executable in the <Quartus II system directory>\bin directory.
Jam STAPL Players
Supported Download Cables
ByteBlaster™ II, ByteBlasterMV, and ByteBlaster parallel port download cables.
All programming cables are supported by the JTAG server such as the USB-Blaster™, ByteBlaster II, ByteBlasterMV, ByteBlaster,
MasterBlaster™, and EthernetBlaster.
Porting of Source Code to the Embedded Processor
16-bit and 32-bit embedded processors.
Enable or Disable Procedure from the Command-Line Syntax
To enable the optional procedure, use the –d<procedure>=1 option.
To disable the recommended procedure, use the –d<procedure>=0 option.
To disable the recommended procedure, use the –d<procedure> option.
To enable the optional procedure, use the –e<procedure> option.
Altera supports two types of Jam STAPL files: .jam ASCII text files and .jbc byte-code files.
ASCII Text Files (.jam)
Altera supports the following formats of the ASCII text-based .jam:
JEDEC JESD71 STAPL format. Altera recommends that you use this format for new projects. In most cases, you use .jam files in tester environments.
Jam version 1.1 format (pre-JEDEC).
The binary .jbc files are compiled versions of .jam files. A .jbc is compiled to a virtual processor architecture where the ASCII text-based Jam STAPL commands are mapped to byte-code instructions
compatible with the virtual processor.
Jam STAPL Byte-Code .jbc format—compiled version of the JEDEC JESD71 STAPL file. Altera recommends that you use this format in embedded application
to minimize memory usage.
Jam Byte-Code .jbc format—compiled version of the Jam version 1.1 format file.
Generating Byte-Code Jam STAPL Files
The Quartus II software can generate .jam and .jbc files. You can also compile a .jam into a .jbc with the stand-alone Jam STAPL Byte-Code Compiler. The compiler produces a .jbc that is functionally equivalent to the .jam.
The Quartus II software tools support programming and configuration of multiple devices from single or multiple .jbc files. You can include Altera and non-Altera JTAG-compliant devices in the JTAG chain. If you do not specify a programming
file in the Programming File Names field, devices in the JTAG chain are bypassed.
Figure 1. Multi-Device JTAG Chain and Sequence Configuration in Quartus II Programmer
Note: If you convert JTAG chain files to .jam, the Quartus II Programmer options that you select for other devices in the JTAG chain are not programmed into the new .jam. The Quartus II Programmer ignores your programming options while you are creating a multi-device .jam or JTAG Indirect Configuration (.jic) file. However, you can choose the programming options to apply to the device when you use the Jam STAPL Player with the
generated .jam. For a multi-device .jam, the programming options you choose are applied to each device that has a data file in the JTAG chain.
On the Quartus II menu, select Tools > Programmer.
Click Add File and select the programming files for the respective devices.
On the Quartus II Programmer menu, select File > Create/Update > Create Jam, SVF, or ISC File.
In the File Format list, select a .jbc format.
Figure 2. Generating a .jbc for a Multi-Device JTAG Chain in the Quartus II Software
List of Supported .jam and .jbc Actions and Procedures
A .jam or .jbc consists two types of statements: action and procedure.
Action—a sequence of steps required to implement a complete operation.
Procedure—one of the steps contained in an action statement.
An action statement can contain one or more procedure statements or no procedure statement. For action statements that contain
procedure statements, the procedure statements are called in the specified order to complete the associated operation. You
can specify some of the procedure statements as “recommended” or “optional” to include or exclude them in the execution of
the action statement.
Table 2. Supported .jam or .jbc Actions and Optional Procedures for Each Action in Altera Devices
Definitions of .jam and .jbc Action and Procedure Statements
Table 3. Definitions of .jam Action Statements
Programs the device.
Checks the erased state of the device.
Verifies the entire device against the programming data in the .jam or .jbc.
Performs a bulk erase of the device.
Returns the JTAG USERCODE register information from the device.
Configures the device.
Specifies that the configuration device configures the attached devices immediately after programming.
Compares the actual device IDCODE with the expected IDCODE generated in the .jam and .jbc.
Table 4. Definitions of .jam Procedure Statements
When enabled, the device is
When enabled, the security bit of the
device is set.
When enabled, the player reads the
JTAG USERCODE of the device and prints it to the screen.
When enabled, the ISP clamp mode of
the device is ignored.
When enabled, the procedure allows the
industrial low temperature ISP for MAX 3000A, 7000B, and 7000AE
When enabled, the procedure performs
the specified action only on the user flash memory (UFM).
When enabled, the procedure performs
the specified action only on the configuration flash memory
When enabled, the real-time ISP
feature is turned on for the ISP action being executed.
When enabled, the configuration device
configures the attached device immediately after programming.
When enabled, the procedure halts the
auto-configuration controller to allow programming using the JTAG
interface. The nSTATUS pin remains low even after the device is
When enabled, the procedure allows
configuration of the device even if an IDCODE error exists.
When enabled, the procedure erases the
common flash interface (CFI) flash memory that is attached to the
parallel flash loader (PFL) of the MAX 10, MAX V, or MAX II
When enabled, the procedure removes
the protection mode of the serial configuration devices (EPCS).
When Enabled, during Programming, the data is
By default, operations will be targeted on fullchip
(except read back). However if this procedure is enabled, ICB settings
will be excluded.
By default, operations will be targeted on fullchip
(except read back). However if this procedure is enabled, CFM1 sector
(if present) will be excluded.
When this option is set, CRAM is upgraded (= internal
reconfiguration) automatically on the timing pof was loaded to CFM. This
option is used with real_time_isp.
Jam STAPL Player and quartus_jli Exit Codes
Exit codes are the integer values that indicate the result of an execution of a .jam or .jbc. An exit code value of zero indicates success. A non-zero value indicates failure and identifies the general type of failure
Table 5. Exit Codes Defined in Jam STAPL Specification (JEST71). Both the Jam STAPL Player and the quartus_jli command-line executable can return the exit codes listed in this table.
Checking chain failure
Reading IDCODE failure
Reading USERCODE failure
Reading UESCODE failure
Entering ISP failure
Unrecognized device ID
Device version is not supported
Calculating checksum failure
Setting security bit failure
Querying security bit failure
Exiting ISP failure
Performing system test failure
Using the Jam STAPL Player
The Jam STAPL Player commands and parameters are not case-sensitive. You can write the option flags in any sequence.
To specify an action in the Jam STAPL Player command, use the -a option followed immediately by the action statement with no spaces. The following command programs the entire device using
the specified .jam:
Figure 3. Programming an EPM240 Device Using the Jam STAPL Player. This figure shows an example of a successful action with an exit code value of zero.
You can execute the optional procedures associated with each action using the –d option followed immediately by the procedure statement with no spaces. The following command erases only the UFM block of
the device using real-time ISP:
Figure 7. Configuring and Reading the JTAG USERCODE of the EP2C70 Device Using the USB-Blaster Cable
Using Jam STAPL for ISP with an Embedded Processor
Embedded systems contain both hardware and software components. When you are designing an embedded system, lay out the PCB
first. Then, develop the firmware that manages the functionality of the board.
Methods to Connect the JTAG Chain to the Embedded Processor
You can connect the JTAG chain to the embedded processor in two ways:
Connect the embedded processor directly to the JTAG chain
Connect the JTAG chain to an existing bus using an interface device
In both JTAG connection methods, you must include space for the MasterBlaster or ByteBlasterMV header connection. The header
is useful during prototyping because it allows you to quickly verify or modify the contents of the device. During production,
you can remove the header to save cost.
Connecting the Embedded Processor Directly to the JTAG Chain
In this method, four of the processor pins are dedicated to the JTAG interface.
This method is the most straightforward. This method saves board space but reduces the number of available embedded processor
Connecting the JTAG Chain to an Existing Bus Using an Interface Device
In this method, the JTAG chain is represented by an address on the existing bus and the processor performs read and write
operations on this address.
Figure 8. Connecting the JTAG Chain to the Embedded System
Design Schematic of Interface Device
The following figure shows an example design schematic of an interface device. This example design is for your reference only.
If you use this example, you must ensure that:
TMS, TCK, and TDI are synchronous outputs
Multiplexer logic is included to allow board access for the MasterBlaster or ByteBlasterMV download cable
Figure 9. Interface Logic Design Example. Except for the data[3..0] data path, all other inputs in this figure are optional. These inputs are included only to illustrate
how you can use the interface device as an address on an embedded data bus.
The embedded processor asserts the JTAG chain’s address. You can set the R_nW and R_AS signals to notify the interface device when you want the processor to access the chain.
To write—connect the data[3..0] data path to the JTAG outputs of the device using the three D registers that are clocked by the system clock (CLK). This clock can be the same clock used by the processor.
To read—enable the tri-state buffers and let the TDO signal flow back to the processor.
This example design also provides a hardware connection to read back the values in the TDI, TMS, and TCK registers. This optional feature is useful during the development phase because it allows the software to check the valid
states of the registers in the interface device.
In addition, the example design includes multiplexer logic to permit a MasterBlaster or ByteBlasterMV download cable to program
the device chain. This capability is useful during the prototype phase of development when you want to verify the programming
When you lay out a board that programs or configures the device using the IEEE Std. 1149.1 JTAG chain, you must observe several
Treat the TCK Signal Trace as a Clock Tree
The TCK signal is the clock for the entire JTAG chain of devices. Because these devices are edge-triggered by the TCK signal, you must protect the TCK signal from high-frequency noise and ensure that the signal integrity is good.
Ensure that the TCK signal meets the rise time (tR) and fall time (tF) parameters specified in the data sheet of the relevant device family.
You may also need to terminate the signal to prevent overshoot, undershoot, or ringing. This step is often overlooked because
the signal is software-generated and originated at a processor general-purpose I/O pin.
Use a Pull-Down Resistor on the TCK Signal
You must hold the TCK signal low using a pull-down resistor to keep the JTAG test access port (TAP) in a known state at power-up.
A missing pull-down resistor can cause a device to power-up in the state of JTAG and its boundary-scan test (BST). This situation
can cause conflicts on the board.
A typical resistor value is 1 kΩ.
Make the JTAG Signal Traces as Short as Possible
Short JTAG signal traces help eliminate noise and drive-strength issues.
Give special attention to the TCK and TMS pins. Because TCK and TMS signals are connected to every device in the JTAG chain, these traces see higher loading than the TDI or TDO signals.
Depending on the length and loading of the JTAG chain, you may require additional buffering to ensure the integrity of the
signals that propagate to and from the processor.
Add External Resistors to Pull the Outputs to a Defined Logic Level
During programming or configuration, you must add external resistors to the output pins to pull the outputs to a defined logic
The output pins tri-state during programming or configuration. Additionally, on MAX® 7000, FLEX® 10K, APEX™ 20K, and all configuration devices, the pins are pulled up by a weak internal resistor—for example, 50 kΩ.
However, not all Altera devices have weak pull-up resistors during ISP or in-circuit reconfiguration. For information about
which device has weak pull-up resistors, refer to the data sheet of the relevant device family.
Note: Altera recommends that you tie the outputs that drive sensitive input pins to the appropriate level using an external resistor
on the order of 1 kΩ. You may need to analyze each of the preceding board layout elements further, especially signal integrity.
In some cases, analyze the loading and layout of the JTAG chain to determine whether you need to use discrete buffers or a
The embedded Jam STAPL Player is able to read .jam that conforms to the standard JEDEC file format and is backward compatible with legacy Jam version 1.1 syntax. Similarly,
the Jam STAPL Byte-Code Player can play .jbc compiled from Jam STAPL and Jam version 1.1 .jam.
The Jam STAPL Byte-Code Player
The Jam STAPL Byte-Code Player is coded in the C programming language for 16 bit and 32 bit processors. A specific subset
of the player source code also supports some 8 bit processors.
The source code for the 16 bit and 32 bit Jam STAPL Byte-Code Player is divided into two categories:
jbistub.c—platform-specific code that handles I/O functions and applies to specific hardware.
All other C files—generic code that performs the internal functions of the player.
Figure 10. Jam STAPL Byte-Code Player Source Code Structure. This shows the organization of the source code files by function. The process of porting the Jam STAPL Byte-Code Player to
a particular processor is simplified because the platform-specific code is all kept inside jbistub.c.
The default configuration of jbistub.c includes the code for DOS, 32 bit Windows, and UNIX. Because of this configuration, the source code is compiled and evaluated
for the correct functionality and debugging on these operating systems.
For embedded environments, you can remove this code with a single #define preprocessor statement. In addition, porting the code involves making minor changes to specific parts of the code in jbistub.c.
Table 7. Functions Requiring Customization. This table lists the jbistub.c functions that you must customize to port the Jam STAPL Byte-Code Player.
Provides interfaces to the four IEEE 1149.1 JTAG signals, TDI, TMS, TCK, and TDO.
Passes information, such as the user electronic signature (UES), back to the calling program.
Implements the programming pulses or delays needed during execution.
Processes signal-to-pin map for non-IEEE 1149.1 JTAG signals.
Asserts non-IEEE 1149.1 JTAG signals as defined in the VECTOR MAP.
Perform the steps in the following sections to ensure that you customize all the necessary codes.
Step 1: Set the Preprocessor Statements to Exclude Extraneous Code
To eliminate DOS, Windows, and UNIX source code and included libraries, change the default PORT parameter to EMBEDDED.
Add this code to the top of jbiport.h:
#define PORT EMBEDDED
Step 2: Map the JTAG Signals to the Hardware Pins
The jbi_jtag_io() function in
jbistub.c contains the code that sends and
receives the binary programming data. By default, the source code writes to the parallel
port of the PC. You must remap all four JTAG signals to the pins of the embedded
Figure 11. Default PC Parallel Port Signal Mapping. This figure shows the jbi_jtag_io() signal mapping of the JTAG pins to the parallel port registers of the PC. The PC parallel port hardware inverts the most
significant bit: TDO.
PC Parallel Port Signal Mapping Sample Source Code for jbi_jtag_io()
int jbi_jtag_io(int tms, int tdi, int read_tdo)
int data = 0;
int tdo = 0;
jtag_hardware_initialized = TRUE;
data = ((tdi ? 0x40 : 0) | (tms ? 0x2 : 0)); /*TDI,TMS*/
tdo = (read_byteblaster(1) & 0x80) ? 0 : 1; /*TDO*/
write_blaster(0, data | 0x01); /*TCK*/
The PC parallel port inverts the actual value of TDO. Because of this, the jbi_jtag_io() function in the preceding code inverts the value again to retrieve the original data in the following line:
tdo = (read_byteblaster(1) & 0x80) ? 0 : 1;
If your target processor does not invert TDO, use the following code:
tdo = (read_byteblaster(1) & 0x80) ? 1 : 0;
To map the signals to the correct addresses, use the left shift (<<) or right shift (>>) operator. For example, if TMS and TDI are at ports 2 and 3, respectively, use this code:
The read_byteblaster and write_byteblaster signals use the inp() and outp() functions from the conio.h library, respectively, to read and write to the port. If these functions are not available, you must substitute them with
Step 3: Handle Text Messages from jbi_export()
The jbi_export() function uses the printf() function to send text messages to stdio.
The Jam STAPL Byte-Code Player uses the jbi_export() signal to pass information, for example, the device UES or USERCODE, to the operating system or software that calls the Jam
STAPL Byte-Code Player. The function passes text and numbers as strings and decimal integers, respectively.
If there is no stdout device available, the information can be redirected to a file or storage device, or passed back as a variable to the program
that called the player.
The calibrate_delay() function determines how many loops the host processor runs in a millisecond. This calibration is important because accurate
delays are used in programming and configuration.
By default, this number is hardcoded as 1,000 loops per millisecond and represented as:
one_ms_delay = 1000
If this parameter is known, adjust it accordingly. Otherwise, use code similar to the code included for Windows and DOS platforms
that counts the number of clock cycles it takes to execute a single loop. This code has been sampled over multiple tests and,
on average, produces an accurate delay result. The advantage to this approach is that calibration can vary based on the speed
of the host processor.
After the Jam STAPL Byte-Code Player is ported and working, verify the timing and speed of the JTAG port at the target device.
Timing parameters for the supported Altera devices must comply with the JTAG timing parameters and values provided in the
data sheet of the relevant device family.
If the Jam STAPL Byte-Code Player does not operate within the timing specifications, you must optimize the code with the appropriate
delays. Timing violations can occur in powerful processors that can generate TCK at a rate faster than 10 MHz.
Note: To avoid unpredictable Jam STAPL Byte-Code Player operation, Altera strongly recommends keeping the source code files other
than jbistub.c in their default state.
Jam STAPL Byte-Code Player Memory Usage
The Jam STAPL Byte-Code Player uses memory in a predictable manner. You can estimate the ROM and RAM usage.
Estimating ROM Usage
Figure 12. Equation to Estimate the Maximum Required ROM Size. Use this equation to estimate the maximum amount of ROM required to store the Jam STAPL Byte-Code Player and the .jbc.
The .jbc size can be separated into these categories:
The amount of memory required to store the programming data.
The space required for the programming algorithm.
Figure 13. Equation to Estimate .jbc Size.
This equation provides a .jbc size estimate that may vary by ±10%, depending on device utilization. If device utilization is low, .jbc sizes tend to be smaller because the compression algorithm used to minimize file size will more likely find repetitive data.
This equation also indicates that the algorithm size stays constant for a device family but the programming data size grows
slightly as more devices are targeted. For a given device family, the increase in the .jbc size caused by the data component is linear.
Alg stands for space used by the algorithm
Data stands for space used by the compressed programming data
k stands for the index representing the device being targeted
N stands for the number of target devices in the chain
Algorithm File Size Constants
Table 8. Algorithm File Size Constants Targeting a Single Altera Device Family
Table 9. Algorithm File Size Constants Targeting Multiple Altera Device Families. This table lists the algorithm file size constants for possible combinations of Altera device families that support the Jam
8 There is a minimum limit of 64 kilobits (Kb) for compressed arrays with the .jbc compiler. Programming data arrays that are smaller than 64 Kb (8 kilobytes (KB)) are not compressed. The EPM240 programming
data array is below the limit, which means that the .jbc files are always uncompressed. A memory buffer is needed for decompression. For small embedded systems, it is more efficient
to use small uncompressed arrays directly rather than to uncompress the arrays.
9 The file size is design dependent.
Refer to the generated .jbc file for the file
Jam STAP Byte-Code Player Size
Table 11. Jam STAPL Byte-Code Player Binary Size. Use the information in this table to estimate the binary size of the Jam STAPL Byte-Code Player
Pentium/486 using the MasterBlaster or ByteBlasterMV download cables
Pentium/486 using the MasterBlaster or ByteBlasterMV download cables
Estimating Dynamic Memory Usage
Figure 14. Equation to Estimate Maximum Required DRAM. Use this equation to estimate the maximum amount of DRAM required by the Jam STAPL Byte-Code Player.
The .jbc size is determined by a single-device or multi-device equation.
The amount of RAM used by the Jam STAPL Byte-Code Player is the total size of the .jbc and the sum of the data required for each targeted device. If the .jbc file is generated using compressed data, then some RAM is used by the player to uncompress and temporarily store the data.
If you use an uncompressed .jbc, the RAM size is equal to the uncompressed .jbc size.
Note: The memory requirements for the stack and heap are negligible in terms of the total amount of memory used by the Jam STAPL
Byte-Code Player. The maximum depth of the stack is set by the JBI_STACK_SIZE parameter in jbimain.c.
Example of Calculating DRAM Required by Jam STAPL Byte-Code Player
To determine memory usage, first determine the amount of ROM required and then estimate the RAM usage.
This example uses a 16-bit Motorola 68000 processor to program EPM7128AE and EPM7064AE devices in an IEEE Std. 1149.1 JTAG
chain using a compressed .jbc.
Use the multi-device equation to estimate the .jbc size.
Figure 15. Multi-Device Equation to Estimate .jbc Size
Because the .jbc file contains compressed data, use the compressed data file size constants to determine the data size. Refer to the related
In this example, Alg is 21 KB and Data is the sum of EPM7064AE and EPM7128AE data sizes (8 KB + 4 KB = 12 KB).
The the .jbc file size is 33 KB.
Estimate the Jam STAPL Byte-Code Player size—this example uses a Jam STAPL Byte-Code Player size of 62 KB because the Motorola
68000 processor is a 16 bit processor. Use the following equation to determine the amount of ROM required. In this example,
the ROM size is 95 KB.
Figure 16. Equation to Estimate the Maximum Required ROM Size
Estimate the RAM usage using the following equation. In this example, the .jbc size is 33 KB.
Figure 17. Equation to Estimate Maximum Required DRAM
Because the .jbc uses compressed data, add up the uncompressed data size for each device to find the total amount of RAM usage. Refer to the
The uncompressed data size constants for EPM7064AE and EPM7128AE are 8 KB and 12 KB, respectively.
The total DRAM usage in this example is calculated as RAM Size = 33 KB + (8 KB + 12 KB) = 53 KB.
In general, .jam files use more RAM than ROM. This characteristic is desirable because RAM is cheaper. In addition, the overhead associated
with easy upgrades becomes less of a factor when programming a large number of devices. In most applications, the importance
of easy upgrades outweigh memory costs.
To update a device in the field, download a new .jbc and run the Jam STAPL Byte-Code Player, in most cases, with the program action statement.
The main entry point for the Jam STAPL Byte-Code Player is jbi_execute(). This routine passes specific information to the player. When the player finishes, it returns an exit code and detailed error
information for any run-time errors. The interface is defined by the routine’s prototype definition in jbimain.c:
The code within main() in jbistub.c determines the variables that are passed to jbi_execute(). In most cases, this code is not applicable to an embedded environment. Therefore, you can remove this code and set up the
jbi_execute() routine for the embedded environment.
Before calling the jbi_execute function, construct init_list with the correct arguments that correspond to the valid actions in .jbc, as specified in the JEDEC standard JESD71 specification. The init_list is a null-terminated array of pointers to strings.
An initialization list tells the Jam STAPL Byte-Code Player the types of functions to perform—for example, program and verify—and
this list is passed to jbi_execute(). The initialization list must be passed in the correct manner. If an initialization list is not passed or the initialization
list is invalid, the Jam STAPL Byte-Code Player simply checks the syntax of the .jbc and if there is no error, returns a successful exit code without performing the program function.
Code to Set Up init_list for Performing Program and Verify Operation
Use this code to set up init_list that instructs the Jam STAPL Byte-Code Player to perform a program and verify operation.
The default code in the Jam STAPL Byte-Code Player sets init_list differently and is used to give instructions to the Jam STAPL Byte-Code Player from the command prompt.
The code in this example declares the init_list variable while setting it equal to the appropriate parameters. The CONSTANT_AREA identifier instructs the compiler to store the init_list array in the program memory.
After the Jam STAPL Byte-Code Player completes a task, the player returns a status code of type JBI_RETURN_TYPE or integer.
A return value of "0" indicates a successful action. The jbi_execute() routine can return any of the exit codes as defined in the Jam STAPL Specification.
Table 12. Parameters in the jbi_execute() Routine. You must pass the mandatory parameters for the Jam STAPL Byte-Code Player to run.
A pointer to the .jbc. For most embedded systems, setting up this parameter is as easy as assigning an address to the pointer before calling jbi_execute().
Amount of memory (in bytes) that the .jbc occupies.
A pointer to dynamic memory that can be used by the Jam STAPL Byte-Code Player to perform its necessary functions. The purpose
of this parameter is to restrict the player memory usage to a predefined memory space. This memory must be allocated before
If the maximum dynamic memory usage is not a concern, set this parameter to null, which allows the player to dynamically allocate
the necessary memory to perform the specified action.
A scalar representing the amount of memory (in bytes) to which workspace points.
A pointer to a string (text that directs the Jam STAPL Byte-Code Player). Example actions are PROGRAM or VERIFY. In most cases, this parameter is set to the string PROGRAM. The text can be in upper or lower case because the player is not case-sensitive.
The Jam STAPL Byte-Code Player supports all actions defined in the Jam STAPL Specification.
Take note that the string must be null-terminated.
An array of pointers to strings. Use this parameter when applying Jam version 1.1 files, or when overriding optional sub-actions.
Altera recommends using the STAPL-based .jbc with init_list. When you use a STAPL-based .jbc, init_list must be a null-terminated array of pointers to strings.
A pointer to a long integer. If an error is encountered during execution, the Jam STAPL Byte-Code Player records the line
of the .jbc where the error occurred.
A pointer to a long integer. Returns a code if there is an error that applies to the syntax or structure of the .jbc. If this kind of error is encountered, the supporting vendor must be contacted with a detailed description of the circumstances
in which the exit code was encountered.
Calling the Jam STAPL Byte-Code Player is like calling any other subroutine. In this case, the subroutine is given actions
and a file name, and then it performs its function.
In some cases, you can perform in-field upgrades depending on whether the current device design is up-to-date. The JTAG USERCODE
value is often used as an electronic "stamp" that indicates the device design revision. If the USERCODE is set to an older
value, the embedded firmware updates the device.
The following pseudocode shows how you can call the Jam Byte-Code Player multiple times to update the target Altera device:
result = jbi_execute(jbc_file_pointer, jbc_file_size, 0, 0,\
"READ_USERCODE", 0, error_line, exit_code);
The Jam STAPL Byte-Code Player reads the JTAG USERCODE and exports it using the jbi_export() routine. The code then branches based on the result.
With Jam STAPL Byte-Code software support, updates to the supported Altera devices are as easy as adding a few lines of code.
You can use a switch statement, as shown in this example, to determine which device needs to be updated and which design revision
you must use.
case "0001": /*Rev 1 is old - update to new Rev*/
result = jbi_execute (rev3_file, file_size_3, 0, 0,\
"PROGRAM", 0, error_line, exit_code);
case "0002": /*Rev 2 is old - update to new Rev*/
result = jbi_excecute(rev3_file, file_size_3, 0, 0,\
"PROGRAM", 0, error_line, exit_code);
; /*Do nothing - this is the current Rev*/
default: /*Issue warning and update to current Rev*/
Warning - unexpected design revision;
/*Program device with newest Rev anyway*/
result = jbi_execute(rev3_file, file_size_3, 0, 0,\
"PROGRAM", 0, error_line, exit_code);
Document Revision History
Added optional .jam procedures in Supported .jam or .jbc
Actions and Optional Procedures for Each Action in Altera
Added .jam procedure statement and description in
Definitions of .jam Procedure Statements.
Updated the typical jam STAPL byte-code data size for
MAX V and MAX 10 devices in Data Constants for Altera Devices Supporting
the Jam Language (for ISP) table.
Added information for MAX 10 devices.
Added the "do_epcs_unprotect" optional .jam procedure for serial configuration devices to disable EPCS protection mode.
Restructured and rewrote several sections for clarity and style update.
Changed chapter and topic titles ("Differences Between the Jam STAPL Players and quartus_jli" on page 2, "ASCII Text Files"
on page 3, "Byte-Code Files" on page 3, "Generating Jam STAPL Files" on page 3, "Using the quartus_jli Command-Line Executable"
on page 10, and "Embedded Jam STAPL Players" on page 16).
Updated all screenshots.
Updated several table and figure titles (minor text changes).
Added information for MAX V devices.
Corrected text errors in Figure 9.
Updated codes in "Step 2: Map the JTAG Signals to the Hardware Pins" and "Updating Devices Using Jam".
Updated equations for clarity. Involves changes in equations numbering throughout the document.
Corrected minor error in "Notes to Table 9:" on page 23.