Running Code that Resides in Other Files

It's common for a test function to be needed by more than one test device file. For example, files for SPI devices require code that implements the SPI protocol so that data can be transferred over the bus. Instead of inserting that code into every SPI test device file, it is better to save it as common functionality; the shared functions are stored within additional code files.

The XJTAG XJEase library contains many additional code files, and users can create their own and manage them in custom libraries. This section describes how to add library files to a test device file, and then how to create new ones.

Adding an Additional Code File

Follow these steps to add an additional code file:

1. Select the file from an XJEase library or from disk.
2. Ensure the bus names used in the test device file match those in the additional code file.
3. Add any required constants to the test device file.

All these steps are described in detail below.

1: Select the File

As an example, consider a device with an SPI interface: to implement a test that uses its SPI bus, it is necessary to add a function that controls the bus. This is done from the Test Device Files screen in XJDeveloper by opening a device file, going to the Additional Code Files tab and then selecting From Library... from the Add... menu:

Click From Library... to add an additional code file from an XJEase library Click From File... to add a user-created additional code file

Figure 19: Adding an Additional Code File

This will open the XJEase Library Browser as shown below in Figure 20, displaying only those files that can be used as additional code files.

The XJTAG library includes files with functions for operations such as:

• Communicating over busses such as I²C and SPI (the relevant additional code files are in the Protocols category)
• Performing mathematical operations and other useful functions such as millivolt to Volt conversion (Math.xje is in the Utility category)
• Calculating CRCs (CRC.xje is in the Utility category)
• Loading binary, hex, and S-record programming files into a variable (DataReader.xje is in the Utility category)
• Checking clocks and oscillators are toggling (available in the Clocks, Oscillators & Crystals category)

To add the required additional code file, highlight its filename and click Select as shown in Figure 20. To check which functions it contains before adding it, click the View button while the file is highlighted. This will open a file viewer. XJTAG Library files list their available functions in comment text at the top.

Continuing with the example above, the file SPI.xje has been selected because that is the additional code file that contains functions that read and write on the SPI bus:

1: Select Categories to group files by type 2: Select the relevant code file category 3: Highlight required file from this list 4: Click to view contents of highlighted file 5: Click the Add to projects button to select file

Figure 20: Selecting an Additional Code File

Clicking Select saves a copy of the file to the project directory. A reference to it will also be added to that device's Additional Code Files list.

Save the updated test device file by clicking the Save button above the Navigator pane as shown in Figure 21 below (not the Save Project button in the very top toolbar, which saves the project). If you're using the protocol files, the project is likely to have errors at this point because the bus names used in the code probably won't match those in the test device file. Those errors will be cleared when bus names are adjusted as described in the next section.

Added additional code files are listed here Click this button to update the test device filespan>

Figure 21: Saving an Updated Test Device File

Once the test device file has been saved, the additional code file will appear in the Navigator pane:

Figure 22: An Associated Additional Code File

• When multiple additional code files are associated with a test device file, it is important to note that they are parsed in the order they appear. If an expression in one file uses a function that is defined in a different file, the one containing the function must appear first in the list unless the function has been defined using the DECLARE keyword.

• Although it is possible to add calls to functions that reside in circuit code files, this is rarely done because it can easily cause problems with the function's scope and lead to code that is not easy to reuse. If it is done, the circuit code files will not be explicitly linked to the test device file and so will not appear in this hierarchy.

After the test device has been saved, the functions provided by the additional code file will be available for use in the test device file.

• To discover what functions are available in a file, the Function button provides a quick way to find them:
• 
• Clicking the Function button will display a list of functions available in the current file and, below the line, menus that list other available functions. Clicking on one of the listed functions will take you straight to its code.

2: Ensure Bus Names Match Those in the Additional Code File

If the additional code file interacts with the busses, it will assume they have been given certain names in the test device file. For example, the protocol file for SPI requires that there are busses called SCLK, SDIN and SDOUT. It is therefore important to ensure the device's relevant busses are given matching names. XJDeveloper's Errors pane will list the bus names that haven't been found.

If the file comes from the XJTAG XJEase library, the top section of the file will include comments that describe the code's function and how to use it. This includes any required bus names, together with the number of pins expected in each bus (where a fixed bus width is required).

In some situations XJDeveloper may offer to automatically create the busses if they are missing.

If busses are not automatically created or names do not match exactly, then to set the names in the test device file, first view the contents of the additional code file to see how these busses need to be defined. This is done by double-clicking on the name of the file in the device's Additional Code Files list.

The bus names used in the test device file should now be checked to ensure they match, and edited if necessary (to return to the device's Busses list to view and edit bus names, select the Busses tab at the bottom of the test device file - see Figure 23).

Select the test device file Click Busses to view the pin names being used

Figure 23: Returning to the Busses Pane

• Bus names are case-sensitive.

• If the names in a device's Busses list do not match those in an associated additional code file, it is best to change the names of the device's busses rather than editing the additional code file. There are several reasons for this:
• • It requires only one change, whereas altering a name in the additional code file can lead to many SET calls having to be edited.
  • Other files may be using the additional code file, so changing the bus name in the additional code file will require it to be changed in every test device file that calls it.
  • Modifying the additional code file will lead to more work when accepting library updates.

3: Add Required Constants to the Test Device File

The additional code file may require some constants to be set – for example, to define an I²C device's address. XJEase library files will list any such requirements in the comments at the start of the file.

These constants need be set in the test device file, and there are two ways this can be done:

• Hardcode a value into the test device file (suitable if that value will never change)
• Use a Configuration Variable to set the value of the constant (this is the best method for constants that might need changing when the device is used in multiple places or in other projects, such as an I²C address that is configured via the device's pins)

If a value is never going to change for all devices that use the file, the simplest approach is to hardcode the value for the constant. This can be done by copying the required lines of code from the additional code file's comments and pasting them into the code editor window for the test device file. In the example below, an I²C address is being set as well as various page sizes. The code has been copy/pasted from the comments in the IIC.xje file:

Copy constants from the additional code file comments and paste into the top-level device file

Figure 24: Adding Constants to a Test Device File

After pasting the constant definitions into the top of the file, click the  button to save the changes.

If the constant being defined could need a different value when the device is used elsewhere in the circuit or in another project, it is better to set the value using a Configuration Variable rather than hard-coding it. This will greatly simplify reuse. This time, only constants that are independent of the device implementation are pasted into the top of the file: in the example shown in Figure 24, the integer declaration of IIC_ADDRESS would now be omitted from the code because it will now be made a Configuration Variable instead. The page sizes are still hard-coded because they will not change if the device is used elsewhere. The process for using Configuration Variables is described in Creating Constants That Can Be Changed for Alternative Device Configurations.

• The XJDeveloper tutorial exercise Adding Additional Code Files to Device Files guides users through the steps with a worked example.

Some Useful Library Test Functions

Many useful test functions are available from the library's standard additional code files. The most commonly used ones include:

• IIC_CheckPresent(): checks that an I²C device responds to a given address. This function is in the additional code file IIC.xje in the Protocols category.
• IIC_FindDevice(): scans all available I²C addresses to discover which ones are in use. This can be helpful when working on a board for which full design data isn't available but you need to know its devices' addresses. This function is in the additional code file IIC.xje in the Protocols category.
• IIC_Write() and IIC_Read(): to write and read bytes over the I²C bus. These functions are in the additional code file IIC.xje in the Protocols category.
• Functions to control an SPI bus, which can be found in the SPI.xje additional code file, which is in the Protocols category.
• TestOscillator(): checks clock lines. It cannot measure a clock frequency because boundary scan does not scan fast enough, but it instead checks for a series of transitions that demonstrate the line is toggling. This is in the additional code file Oscillator.xje.
• Various mathematical functions such as Min() and Max(), and formatters like FormatVoltage(), which performs millivolt to Volt conversion. These are in the additional code file Math.xje in the Utility category.
• CrcCalculate(): generates a cyclic redundancy code for a data stream. This is in the additional code file CRC.xje in the Utility category.
• ReadSRecordFile(), ReadHEXFile(), and ReadBINFile(): load programming files into a variable. These are in the additional code file DataReader.xje in the Utility category.

Creating a New Additional Code File

If a suitable additional code file does not already exist, a new one can be created: from the test device file; select the Additional Code Files tab as before, then click Add.... Within the drop down click New...:

"Click the New... buttton on the Add... drop-down of the Additional Code Files tab"

Figure 25: Creating a New Additional Code File

Provide a meaningful name and click Save to create the file. The new file will be shown in the Additional Code Files pane:

Double-click to start editing your file

Figure 26: Editing a Newly Created Additional Code File

Double-clicking on the name of the new file will open a fresh tab in the editor in which the code can be entered.

• The additional code files supplied by XJTAG are free for users to copy as the basis of their own files (but please refer to www.xjtag.com/support/xjease_code_licence for copyright conditions). If a file similar to what you need is available, it can be easiest to copy/paste part or all of the existing file into the blank file you have created and then edit it to create the new one.

Keeping Up to Date with The Latest Library Files

When XJDeveloper makes a copy of a library file in the project directory, it also records the file's version number. If a more up-to-date version of the library file subsequently becomes available, the user will be notified and given the opportunity to update.

See the user guide on Keeping Library Files Up to Date for more details.

• If the user edits an additional code file (either a library file or a user-created one), it is important to remember that the file is likely to be used by multiple test device files or circuit code files. Care must therefore be taken when editing to ensure that changes do not adversely affect any of the other devices that use it.