XJEase Exercises

This exercise will demonstrate the use of some features of the XJEase language. XJEase has many features, not all of which are covered in this exercise. For more details look at the XJEase Language section of this help system. The exercise builds on the completed demo project: CompletedTutorial4.zip.

The exercise is divided into sections:

• Section 1: Circuit Code File Function
• Section 2: Test Device File Function
• Section 3: Integer Operations
• Section 4: Simple Memory Testing
• Section 5: Multiple Device Testing

Unlike most of the other exercises in this tutorial, this exercise does not give full step-by-step instructions. It tells you what each function should do and gives you information about the language features needed to implement that functionality. There are example functions at the end of each section in case you have any problems getting your version running correctly.

After each section of the exercise, sample solutions are provided for each of the tasks in the section, with a button to reveal them. The sample solution is unlikely to be the only way to accomplish the task but if you get stuck then it shows you a way it could be done. And even when you succeed at the task, the example may be worth checking to see if there was an easier way to do it.

XJEase is used to write functions in two sections of XJDeveloper:

• Test Device Files – functions in these files are used to interact with the functionality of individual devices that don’t implement boundary scan, such as memory devices, sensors, LEDs etc.
• Circuit Code Files – functions in these files have a wider scope than those in Test Device Files. Importantly, they cannot directly control the pins of devices on the board.

Section 1: Circuit Code File Function

The first function that you are going to create will be in a Circuit Code File. This code that you write will first demonstrate how to print text to the Test Output pane on the Run Tests screen. You will then move on to add looping and conditional branching language features.

A new GLOBAL function will have been automatically created in your new file to show you the structure of a function in XJEase. This function can be used as a template or directly modified to contain your code.

More generally XJEase functions take the form:

FunctionName(inputParameterList)(outputParameterList)
    // XJEase Statements
END;

The parameter lists are comma-separated and specify both the Type and Name of each parameter. Input parameters are passed by value so any changes you make to those in your function have no effect in the calling function. Output parameters are passed by reference so that any changes you make will be reflected in the variable specified in the calling function.

Functions that you need to call directly in XJRunner must have a single integer output parameter that defines whether the test has passed or failed. Most commonly such functions will have no input parameters, but it is possible to use functions that do have them.

When developing XJEase code, the editor will use multiple colours. Language keywords, such as END in the case of the example function that has been added to your file, and items such as comments or string and integer values, will show as different colours to improve clarity when reading code.

To get help on language keywords you can press F1 with the text cursor on that word.

You will notice that RESULT_FAIL in the example function is not a reserved word, it is a GLOBAL constant defined in another Circuit Code File, Globals.xje.

The assignment of RESULT_FAIL to the result variable is done with the := operator. In XJEase := is used for assignment and = is used for comparison.

The first function you are going to create will simply print some text to the Test Output pane.

Now that the function exists, it can be added to the XJRunner Setup screen's XJRunner Tests list

To run your function do the following:

You should see that that Hello World is printed when the function runs.

Now that you have some text being output you are going to start to introduce some additional XJEase language features by making yout code output that text multiple times.

The next modification is to format the text that is being output.

To show a different type of looping, modify your code to repeated print Hello World until the operator presses a key on the keyboard.

The previous modification varied the behaviour of the function depending on user feedback but the result was the same whichever key they pressed. For the next modification change the result returned depending on whether the spacebar or a different key is pressed.

So far you have always been printing the same text, for the next modification print strings stored in an array.

That completes section 1 of this exercise. Click the button to see example functions that perform the operations described in each task section above.

GLOBAL MyCircuitCodeFunction()(INT result)
  PRINT("Hello World\n");
  result := RESULT_PASS;
END;

GLOBAL MyCircuitCodeFunction()(INT result)
INT i;
  //Could also be written as i := n FOR 10 where n could be any number as all we want it for the loop to run for 10 iterations
  FOR i := 0 TO 9 
    PRINT("Hello World\n");
  END;
  result := RESULT_PASS;
END;

GLOBAL MyCircuitCodeFunction()(INT result)
  INT i;
  FOR i := 0 TO 9
    PRINT_FORMAT("colour=red,size=150%", "Hello World\n");  
  END;
  result := RESULT_PASS;
END;

GLOBAL MyCircuitCodeFunction()(INT result)
  INT key;

  DO 
    key := GETKEY();
  WHILE key = 0
    PRINT_FORMAT("colour=red,size=150%", " Hello World \n");  
    SLEEP(100);
  END;
  
  result := RESULT_PASS;
END;

GLOBAL MyCircuitCodeFunction()(INT result)
  INT key;
  PRINT("Press spacebar to pass or any other key to fail.\n");

  DO 
    key := GETKEY();
  WHILE key = 0
    PRINT_FORMAT("colour=red,size=150%", " Hello World \n"); 
    SLEEP(100);
  END;
  IF key = 32 THEN  //Can also check IF key = ' '
      result := RESULT_PASS;
  ELSE
      result := RESULT_FAIL;
  END;
END;

GLOBAL PrintArrayHelloWorld()(INT result)
  STRING[][] jaggedArray := {{"1: Hello World Test\n"}, {"\t2: Hello ", "World Test\n"}, {"\t\t3: ", "Hello ", "World ", "Test\n"}};

  //This iterates through 1-D arrays in jaggedArray variable
  FOREACH STRING[] array IN jaggedArray
    //This iterates through the STRINGs in the sub-array
    FOREACH STRING s IN array
      PRINT(s); 
    END;
  END;
  result := RESULT_PASS;
END;

GLOBAL PrintArrayHelloWorld()(INT result)
  INT i, j;
  STRING[][] jaggedArray := {{"1: Hello World Test\n"}, {"\t2: Hello ", "World Test\n"}, {"\t\t3: ", "Hello ", "World ", "Test\n"}};

  //This gives the number of arrays in jaggedArray variable
  FOR i := 0 TO WIDTHOF(jaggedArray)  
    //This gives the number of STRINGs in the sub-array
    FOR j := 0 TO WIDTHOF(jaggedArray[i]) 
      PRINT(jaggedArray[i][j]); 
    END;
  END;
  result := RESULT_PASS;
END;

Section 2: Test Device File Function

This section of the exercise focuses on creating functions in Test Device Files; however, it will also introduce interacting with functions in Test Device Files from Circuit Code functions.

The first function you are going to create will again simply print some text to the Test Output pane.

Add your function to the XJRunner test list for each of the LEDs (because all the LEDs are categorised unit the same file the function will be available to run against all the devices):

At the moment all the LEDs are printing the same message. The next modification is to change the output generated by the function depending on the device that the function is being run against.

To link up the first section of this exercise with this section you are now going to update your Circuit Code File function MyCircuitCodeFunction to run the LED versions you have just created.

It was mentioned above that LED (pin 2).xje used an Additional Code File. The next task is to move your HelloWorld function from LED (pin 2).xje and put it in its own Additional Code File. This will then allow you add this functionality to any device simply by adding your Additional Code File to the device's Test Device File.

That completes section 2 of this exercise. Click the button to see example functions that perform the operations described in each task section above.

GLOBAL HelloWorld()(INT result)
  PRINT("Hello world.\n");
  result := RESULT_PASS;
END;

GLOBAL HelloWorld()(INT result)
  PRINT("Hello world from ", DEVICE_REF, ".\n");
  result := RESULT_PASS;
END;

GLOBAL MyCircuitCodeFunction()(INT result)
  CALL("D1", "HelloWorld ")()(result);
END;

// Your code should look the same as before but the HelloWorld function should now be in the Additional Code File called HelloWorld.xje.

Section 3: Integer operations

This section of the exercise will introduce you to integer variables in XJEase and how they can be manipulated. Please review the help about the Integer variable type as XJEase integers a different to those you may have worked with before.

You will use integer operators including bit manipulation, arithmetic, comparison, bitwise and Boolean operations.

There are a significant number of integer operations that have not been used in this section of the exercise. You can find the full set of the available operators in the main XJTAG help.

That completes section 3 of this exercise. Click the button to see an example function that performs all of the different operations described in the task sections above.

GLOBAL IntegerExample()(INT result)
  INT i WIDTH 4;
  INT mask WIDTH 4 := 0b0100;
  
  //Zero Indexed
  FOR i := 0 TO 9 
    PRINT("Line: ");
    PRINT(i);  
    PRINT(" (0b");
    PRINT(BIN(i));  
    PRINT("): 1 left shifted by the loop counter: 0b");
    PRINT(BIN(1<<i));  
    PRINT(" (decimal ");  
    PRINT(DEC(1<<i));  
    PRINT(")");  
    PRINT("\t\tloop counter (not including bit 0): 0b");
    PRINT(BIN(i[WIDTHOF(i)..1])); 
    PRINT("\t: bitwise complement of the loop counter: 0b");
    PRINT(BIN(~i));
    IF (i & mask) = mask THEN
      PRINT("\t: this loop counts has bit 2 set");
    END;
    PRINT("\n"); 
  END;
  result := RESULT_PASS;
END;

Section 4: Simple Memory Testing

Up to this point all the functions you have developed could have been written in almost any programming language. The main reason why you are learning to write XJEase is to be able to control and monitor the states of pins/nets on a physical PCBA. In this section of the exercise, you will write functions that do interact with the hardware.

The Test Device File used to categorise the SRAM during the tutorial performs a comprehensive test of all the signals on that device. Your first task is to use the read and write cycles from the existing files to implement a much simpler, 'walking ones', test of the pins on the data bus.

Testing an address bus is more complicated than testing a data bus. If you follow the same process as used for the data bus test, i.e. write and then immediately read, then the expected value will almost certainly be read even if there is an issue with an address bus pin. This is because the fault on the address bus will result in the same incorrect address being used for both reading and writing.

To overcome this an address bus test must, as its first stage, write unique data values to the set of addresses resulting from performing a walking one’s pattern across the address bus.

An additional test is needed at address 0 to help find all open circuit faults. If these values can be read back then there will not be any faults with the address bus pins.

That completes section 4 of this exercise. Click the button to see example functions that perform the tests described in the task sections above.

GLOBAL MySRAMTest()(INT result)
  INT data, i, dataBusWidth;
  
  ReadCycle(0)(data);
  dataBusWidth := WIDTHOF(data);
  
  result := RESULT_PASS;
  
  FOR i := 0 TO dataBusWidth-1
    WriteCycle(0, 1 << i, dataBusWidth);
    ReadCycle(0)(data);
    IF data != 1 << i THEN
      result := RESULT_FAIL;
    END;
  END;
END;

GLOBAL MySRAMTest()(INT result)
  INT data, i, dataBusWidth, addressBusWidth;
  
  dataBusWidth := WIDTHOF(DATA);
  addressBusWidth := WIDTHOF(ADDRESS);
  
  result := RESULT_PASS; 

  // address 0 is a special case as a walking 1s will not fully check this bit
  WriteCycle(0, 0xFF, dataBusWidth);
  // now perform the writes using walking 1s value across the address bus
  FOR i := 0 FOR addressBusWidth
    WriteCycle(1 << i, i, dataBusWidth);
  END;
  
  // check the expected data is in each of the locations that was written. 
  // again deal with address 0 first. This is the address that will have been corrupted if there are any open circuit faults.
  ReadCycle(0)(data);
  IF data != 0xFF THEN
    result := RESULT_FAIL;
  END;
  
  // now check the values read using walking 1s across the address bus
  FOR i := 0 FOR addressBusWidth
    ReadCycle(1 << i)(data);
    IF data != i THEN
      result := RESULT_FAIL;
    END;
  END;
END;