Example XJEase code:

STRING pin := "XJDemo.IC5.2";
PRINT_DEVICE_LINK("This is a link to XJDemo.IC5\n", "XJDemo.IC5");
PRINT("DATA[0]'s "); PRINT_NET_LINK("net\n", GET_NET_FROM_PIN(DATA[0]));
PRINT("IC5.2's "); PRINT_PIN_LINK("pin\n", pin);

Output:
This is a link to XJDemo.IC5
DATA[0]‘s net
IC5.2′s pin

There are many variations to the functions shown above, and full documentation and examples can be found in the XJEase help file. The SRAM memory tests in the latest release of the XJEase Library also make full use of the links.

What is the Safe bitstream?

The Safe bitstream is the default binary data that is shifted into the JTAG devices. The aim of the safe bitstream is to disable as much of the board as possible. This means that in general, logic devices that have a chip enable pin will be disabled, and pins on the JTAG devices will be setup as input pins wherever possible.

How is it generated?

The Safe bitstream is generated automatically by XJEase, and derives first of all from the BSDL files in the project. Part of the description of the boundary scan register includes the values needed to disable pins, and what the resulting disabled value will be, so the starting point for the Safe bitstream is one which disables all possible outputs. This starting point is then modified to take account of any constant pins or disable values where signals need to be driven in order to keep other parts of the circuit disabled. For example, the nOE pin on a RAM device would be set to be driven high (by the disable values in the device busses) to stop the data bus becoming active.

In addition to this, XJTAG’s safe bitstream will drive pins which need to be driven in order to prevent logic devices outputting, e.g the enable pin on a buffer chip.

When is it used?

The Safe bitstream is automatically applied on two occasions:

1. Before the first test that accesses the boundary scan registers.
2. At both the beginning and end of the Connection Test.

The user can also cause the Safe bitstream to be applied at any time during device testing by using the in-built SAFE statement.

Warnings and Errors

The most common problem to see relating to the Safe bitstream is a Warning that two conflicting disable values have been set on the same net. In this case XJEase will pick one of the two values. The warning message states which value has been chosen. As with all warnings the project can be run with the warning present but it is best practice to resolve these Safe bitstream conflicts so that the disable values for a net are uniform. It is not safe to rely on the same value always being chosen – updates to XJTAG or modifications to the project may cause it to change.

Calculating the Safe bitstream can also cause an error when you try to run the project (typically at the start, when the safe bitstream is calculated) and testing will stop at this point. The most common cause for the errors is a mistake when defining logic devices in the circuit, causing XJTAG to default the net to a value which is unreachable. If this happens then the error message will list the pins involved in the error and the values they are being set to, so that you can track down the source of the error.

We decided a long time ago that XJTAG should support “simple” logic devices in such a way that the logic is handled transparently when it comes to XJEase code, thus allowing the Test Device code to remain device-centric. We also decided that the built-in connection test had to support logic devices to the same extent. The work was on-going behind the scenes here at XJTAG for some time, and is a major part of the version 2.4 release.

So, in previous versions of XJEase if you had a memory chip with a data bus which was accessed through a buffer, you had to modify the chip’s device file so that the data bus pins were actually the buffer inputs rather than the chip’s own data pins. This will still work… but it’s no longer necessary – XJTAG will now realise (for example) that if you want to write to a particular pin on that data bus then it means setting the appropriate buffer direction, enable and input pins, and that if you later want to read the pin, XJTAG will stop driving the buffer, change the buffer’s direction and then read the value through from the memory.

Limitations

No Logic with State

XJTAG  version 2.4 does not support logic with state.  This does not only apply to individual gates – we also do not support the situation where blocks are combined to store state, for example constructing a flip-flop from NAND gates. XJTAG will attempt to spot such situations and object to them… but if you manage to be more cunning than our compile-time state detection algorithms it still won’t work correctly at runtime!

Wind-up of logic blocks

When you make SET statements in XJEase you are asking XJTAG to put the circuit in a state and leave it that way until told to do otherwise.  And with logic that gets complicated. For example, imagine a logic device with 2 outputs and a truth table set up such that they can’t both output a 1 (ie valid output states are 00, 01, 10 only). The user makes a SET statement that sets the first one high. Fine so far. But then later the user SETs the 2nd one high. Now we have a dilemma. Should we refuse? Or should we set the first one back low in order to comply with the 2nd request? The problem would be worse if there were 3 outputs and any two could be high – which one should we set back low in order to set the 3rd one high?

Because we can’t know what the user actually wants, we will stop and show an error if this situation arises. In general that’s easy for you to get around because having SET a value on a pin, you can always SET a different value on it – so you can SET the first pin back low once you’re done with it (or as you SET the 2nd one high)

If the situation gets far too complicated for you to work out what is causing the conflict, which may mean the SET causing the problem was made in some other test a long way from where you are, then we do have a (slightly drastic) get-out, which is to make a  SAFE; statement in your code. This resets all pins (and logic blocks) in the circuit to their default state.

We hope that the new logic features in XJTAG are useful to you – please give us feedback if you feel you have a situation that we should support and don’t, or if you have further suggestions as to how we can improve the products.

XJEase Functions

For a function to be eligible to be made available to XJRunner it must be in the main project (.xje) file or a device file, or in a code file specified either in the main project (in the Circuit Code Files Screen) or from within a test device file (in the Test Device Files Screen).

Not all functions can be used by XJRunner. In order for an XJEase function to be available it must take no input variables and must return a single integer to indicate pass (value 0) or fail (value 1 or any non-zero value).

i.e. it must be in the format:

FunctionName () (INT result)

CONNTEST

There is always one preset item in the available tests – this is the global function CONNTEST. This runs the automatic connection test.

The XJEase keyword SYSTEM is used to execute a system command or program. It accepts the command in the form of a string and returns the exit code from the program. This is a 32 bit unsigned value in Windows. It can be used execute any program which contains additional tests and then check for success or failure by examining the return code.

All commands are executed using the Windows Command Processor, cmd.exe. If the Command Processor is unable to start the specified command line for any reason it returns an exit code of 1.

Syntax

SYSTEM( STRING command ) ( INTEGER result );

Example

An example of using this is to perhaps run an external program that measures a frequency. In the example below the “MeasureFrequency” program is assumed to return 0 as its exit code if the frequency is between the two values passed in or non-zero if it falls outside.

INT result;

SET TXEN := 1;  // Enable transmitter

SYSTEM("MeasureFrequency.exe 900000 1100000")(result);

SET TXEN := 0;  // Disable transmitter

IF result > 0 THEN
    PRINT("Incorrect frequency detected\n");
    EXIT;
END

By using SYSTEM calls you can therefore run other tests from within XJEase, which can help to integrate all your tests together.

The core of the code is a loop that simply calls the WAITKEY function to read a character of input at a time, until a carriage return is read. As each character is read it is appended to a string that will be returned and also printed to the screen.

STRING text;
INT key;
DO
    key := WAITKEY();
WHILE key := ASC("\n") && key != ASC("\r");
    // ignore any control characters (ASCII value less than 0x20)
    IF key >= 0x20 THEN
        PRINT(CHAR(key));
        text := text + CHAR(key);
    END;
END;

This works reasonably well until the user makes a mistake and wants to backspace. Handling backspace requires us to print the backspace character and remove the last character from the string that we’re building. We can also check the current length of the input string and not allow the user to backspace beyond its start.

INPUTBOX(STRING prompt, STRING title, STRING default)(STRING input)
    STRING text := default;
    INT key;
    INT width;

    ALERT();

    IF title != "" THEN
        PRINT(title, "\n");
    END;
    PRINT(prompt);

    DO
        key := WAITKEY();
    WHILE key := ASC("\n") && key != ASC("\r");
        IF key = ASC("\b") THEN
            width := WIDTHOF(text);
            IF width > 0 THEN
                PRINT("\b");
                IF width = 1 THEN
                    text := "";
                ELSE
                    text := text[width-2..0];
                END;
            END;
        ELSIF key >= 0x20 THEN
            // ignore any control characters (ASCII value less than 0x20)
            PRINT(CHAR(key));
            text := text + CHAR(key);
        END;
    END;

    PRINT("\n");
    input := text;
END;

GetInput()()
    STRING input;
    input := INPUTBOX("Please enter some input and press Enter:", "Input", "");
    PRINT("\nGot \"", input, "\"\n");
END;

The full function appears below, plus an example of its use. It is named INPUTBOX and has the same signature as the upcoming XJEase built-in function, which means once the new version of XJTAG arrives, this function can be deleted and the code will then continue to work. The 3 arguments are the prompt to display, a title and a string that is presented as the default (can be left as an empty string). Note that the example below simply prints the title out, whereas the real INPUTBOX will create a proper dialog box.Note also the use of the ALERT function. If you have more than one XJLink attached in XJRunner, then the output from each is displayed in its own tab; the ALERT function causes the application to draw attention to any tab that requires attention. In XJDeveloper or in XJRunner with just one XJLink attached, then the function has no effect.

The SET statement can perform both reading and writing of the pins. So:

SET nCE := 1;          //set the nCE pin to a logic 1
SET DATA := 0xAA;      //set the data bus ( DATA ) to the HEX value 0xAA
SET readvalue := DATA; //read the current value on the DATA bus into readvalue

Any signals which aren’t changed on a SET statement remain in the same state. All SET statements take one JTAG scan except if you are changing the direction of a bus from writing to reading:

SET DATA := 0xAA;      //write takes one JTAG scan 
SET readValue := DATA; //read statement after write takes 2 scans 

You can set a bus to be tristate by doing the following:

SET DATA := I; // sets the data bus into read mode

Optimisations

Once a pin is in a state, setting it again is optimised away. So the following code only takes one JTAG scan:

SET nCS :=0;
SET nCS :=0;
SET nCS :=0;

You can combine accesses so that they all happen on the same JTAG scan by using a comma:

SET nCS := 0, nOE := 0, DATA :=I ;        // All happen on the same JTAG scan
SET nCS := 1, nOE := 1, readvalue := DATA;// All happen on the same JTAG scan

In the example above all the access happen on the same JTAG scan. There is however a difference in timing between the reading and writing. “readvalue := DATA;” happens first during the "Capture" State in the JTAG state machine. The actual outputting of nCS happens later. This delay is the delay of scanning the JTAG chain and moving the JTAG state machine to the "Update" state. This on a device with 300 bits in the scan chain and running at 10MHz will be about 30μs.

The Write-to-Write time

Providing the JTAG chain speed isn’t restricted due to lack of data then the write-to-write time is just over 30μs (it is a slightly longer path through the JTAG state machine):

SET nCS := 1; //t =0 
SET nOE := 1; //t = 31us 

The Write-to-Read time

The time between writing to one pin and reading another on the following scan is much faster as the time between the "Update" (write) and the "Capture" (Read) is only a few JTAG cycles around the state machine (about 0.3μs in our example). But as explained earlier – if the pin/bus being read is the one which was just written it will take a further complete scan to read the data.

So for SRAM based devices you could have the following read cycle:

SET nWE := 1; // not always needed
SET DATA := I;
SET ADDRESS := Address_To_Read_From;
SET nCS := 0;
SET nOE := 0;
SET Readvalue := DATA;
SET nOE := 1;
SET nCS := 1;
SET nWE := 1;  // not always needed

The above takes a large number of JTAG scans. You can make it much quicker by combining SET statements:

SET nWE := 1;
SET DATA := I, ADDRESS := Address_To_Read_From, nCS := 0, nOE := 0;
SET Readvalue := DATA, nOE := 1 , nCS := 1, nWE :=1; 

If you can be sure nWE is logic 1 before starting then the first SET can be removed.