AN 425: Using the Command-Line Jam™ STAPL Solution for Device Programming

Download PDF
ID 683089
Date 10/14/2024
Public
Document Table of Contents
Document Table of Contents x
1. Using the Command-Line Jam™ STAPL Solution for Device Programming
1. Using the Command-Line Jam™ STAPL Solution for Device Programming x
1.1. Jam™ STAPL Players 1.2. Jam™ STAPL Files 1.3. Using the Jam™ STAPL Player 1.4. Using the quartus_jli Command-Line Executable 1.5. Using Jam™ STAPL for ISP with an Embedded Processor 1.6. Board Layout 1.7. Embedded Jam™ STAPL Players 1.8. Updating Devices Using Jam 1.9. Document Revision History for AN 425: Using the Command-Line Jam™ STAPL Solution for Device Programming
1.1. Jam™ STAPL Players x
1.1.1. Differences Between the Jam™ STAPL Players and quartus_jli
1.2. Jam™ STAPL Files x
1.2.1. Generating Byte-Code Jam™ STAPL Files 1.2.2. List of Supported .jam and .jbc Actions and Procedures 1.2.3. Jam™ STAPL Player and quartus_jli Exit Codes
1.2.2. List of Supported .jam and .jbc Actions and Procedures x
1.2.2.1. Definitions of .jam and .jbc Action and Procedure Statements
1.4. Using the quartus_jli Command-Line Executable x
1.4.1. Command-line Syntax of quartus_jli Command-Line Executable
1.5. Using Jam™ STAPL for ISP with an Embedded Processor x
1.5.1. Methods to Connect the JTAG Chain to the Embedded Processor
1.5.1. Methods to Connect the JTAG Chain to the Embedded Processor x
1.5.1.1. Connecting the Embedded Processor Directly to the JTAG Chain 1.5.1.2. Connecting the JTAG Chain to an Existing Bus Using an Interface Device
1.6. Board Layout x
1.6.1. Treat the TCK Signal Trace as a Clock Tree 1.6.2. Use a Pull-Down Resistor on the TCK Signal 1.6.3. Make the JTAG Signal Traces as Short as Possible 1.6.4. Add External Resistors to Pull the Outputs to a Defined Logic Level
1.7. Embedded Jam™ STAPL Players x
1.7.1. The Jam™ STAPL Byte-Code Player 1.7.2. Steps to Port the Jam™ STAPL Byte-Code Player 1.7.3. Jam™ STAPL Byte-Code Player Memory Usage
1.7.2. Steps to Port the Jam™ STAPL Byte-Code Player x
1.7.2.1. Step 1: Set the Preprocessor Statements to Exclude Extraneous Code 1.7.2.2. Step 2: Map the JTAG Signals to the Hardware Pins 1.7.2.3. Step 3: Handle Text Messages from jbi_export() 1.7.2.4. Step 4: Customize Delay Calibration
1.7.3. Jam™ STAPL Byte-Code Player Memory Usage x
1.7.3.1. Estimating ROM Usage 1.7.3.2. Estimating Dynamic Memory Usage 1.7.3.3. Example of Calculating DRAM Required by Jam™ STAPL Byte-Code Player
1.7.3.1. Estimating ROM Usage x
1.7.3.1.1. Algorithm File Size Constants 1.7.3.1.2. Compressed and Uncompressed Data Size Constants 1.7.3.1.3. Jam™ STAPL Byte-Code Player Size
1.8. Updating Devices Using Jam x
Code to Set Up init_list for Performing Program and Verify Operation 1.8.1. jbi_execute Parameters 1.8.2. Running the Jam™ STAPL Byte-Code Player
1. Using the Command-Line Jam™ STAPL Solution for Device Programming

1.8. Updating Devices Using Jam

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: 
JBI_RETURN_TYPE jbi_execute
(
	PROGRAM_PTR program
	long program_size,
	char *workspace,
	long workspace_size,
	char *action,
	char **init_list,
	int reset_jtag
	long *error_address,
	int *exit_code,
	int *format_version
)

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. 
char CONSTANT_AREA init_list[][] = "DO_PROGRAM=1", "DO_VERIFY=1";

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.


Section Content
jbi_execute Parameters
Running the Jam STAPL Byte-Code Player

Related Information
Level Two Title