Revisions

A revision in XJTAG is defined as any design update to a UUT that requires modifications to the associated XJDeveloper project. In the case where all devices keep the same reference designator XJDeveloper already provides basic support for this by allowing you to edit the netlist of a board. The Revisions feature improves on this to allow projects based on old design data to be updated to produce a brand new, revised project, with much of the setup work automatically completed.

An intelligent device matching algorithm is used to match categorised devices in the source project to the corresponding device in the revision even when the reference designator has changed. Matches are presented as suggestions in a checklist split into a series of stages that guide you through the revision setup process.

Creating a revision

A new revision is created by selecting the Create Revision option on the File menu in XJDeveloper which opens the New Revision Dialog. Here a new netlist, BOM and/or schematic can be entered for each board in the project to be revised.

There are two options for the hierarchy of a revision project and its source project:

• Shared code - All XJEase code files are shared between the two projects so code changes in one project are reflected in the other. The revision project can be in the same directory as the source or a different directory.
• Copied code - All XJEase code files are copied when the new project is created and are then edited independently. The revision project must be in a different directory to the source project.

When a new revision is created, the current project will immediately close and the new project will open, triggering the revision setup process.

Revision projects start out with none of the devices categorised but almost all the other setup is copied from the source project. So the XJRunner test list will already be populated, although obviously unable to run until all the test devices in it are setup. In addition, some of the references to devices in the test list may be out of date if their reference designator has changed. XJDeveloper tracks this by adding the keyword ORIGINAL to the start of all device references (in the test list and elsewhere in the project) when you create the revision. These out of date references get replaced automatically as you work through the Revision Checklist (see below). As such, it is normal to have large number of errors when you start a new revision project but completing the revision setup process should clear them. See Updating Revised Device References for more details.

Revision setup process

N.B. Revision projects differ from standard XJDeveloper projects in that they hold a reference to their source project for comparison purposes. A revision project will never make changes to its source project (with the exception of the XJEase code in any shared files). It is not recommended to edit or move the source project while the revision process is ongoing. This may corrupt the revision project and prevent it from opening.

When the revision project is created it will immediately open and display the Revision Checklist window. The Revision Checklist provides suggestions and recommendations for setting up the new project in the form of items in a checklist. This may take a few seconds to populate. The checklist is designed to work in tandem with the normal XJDeveloper workflow so you can at all times switch between the checklist and any screen in XJDeveloper. However, after making changes to the project outside the checklist it will need to be refreshed to ensure it is up-to-date. Saving and closing the project will store the checklist progress so you can continue from where you left off next time the project is opened.

The Revision Checklist is divided into a series of between 9 and 13 ordered progress stages to help guide you through the process. It is not required to exactly follow this order but there are some restrictions that are enforced to ensure you get the best device matching results. For example, you must setup power and ground nets and your JTAG chain before moving onto other devices. The checklist will repopulate at certain milestones as it gains more information about your project.

Checklist items can be one of 3 different types:

• Tasks - Manual actions to perform to help you setup your project correctly. Examples include categorising any new power nets on the board or checking which devices the BOM has suggested are unfitted.
• Suggested - Suggested device matches are the core of the Revisions feature and the majority of checklist items fit into this category. They allow you to review decisions the device matching algorithm has made and accept or reject its suggestions. (Very high probability device matches are accepted automatically to save time. They can be reviewed under Completed items, see Revision Checklist.)
• Missing - Any categorised devices in the source project for which no match can be found in the revision will appear as missing devices. They serve as a reminder to track down any devices the matching algorithm has missed or, for devices not in this revision of the board, they can be safely ignored.

By default, the checklist only displays items that require action but you can also show completed items to review what you've done so far and/or what the algorithm has categorised for you automatically. Any incorrect completed matches can be undone by clicking Undo on the completed item.

Once you have completed all items in the checklist, the Complete button will be enabled and pressing this will close the checklist window and save the project in its current state. There is no way to review completed items in the checklist after this point so make sure you are happy with everything before continuing. Once completed a revision project reverts to becoming a standard XJDeveloper project with no reference to its source.

N.B. the two projects may still share XJEase code depending on your chosen project hierarchy.

The final step of setting up your new project is to categorise any new devices that were added in this revision. As these devices did not exist in the source project, no suggestions will have appeared for them in the Revision Checklist, but you can use the Categorise Devices screen to set them up as normal.

Device matching

The device matching algorithm is responsible for finding the new instance of any devices categorised in the source project. In the case where the reference designators of all devices have not changed this process is trivial. However, in the case where devices have been renumbered the Revisions feature comes into its own, saving you a lot of manual re-categorisation of devices.

The algorithm pulls in all available data about the old and new revisions of the circuit to recommend 1-to-1 device matches between the source project and the revision. Each match is given a percentage confidence score which is then displayed in the Revision Checklist, 100% indicating a perfect match. Matches which the algorithm is very confident about are accepted automatically, others are presented as suggestions which you can either accept or reject.

When a match is accepted (automatically or manually) a few things happen:

• The device in the new project is categorised to match the device in the source project.
• Any references to the old device are updated to use the new reference designator. For example, in the XJRunner test list, IC4.Test could become IC5.Test. See Updating Device References for more information.
• In the checklist, the Suggested Device Match item is replaced with a Completed Device Match item that has an Undo option.

Pressing Undo on a Completed Device Match item will revert all of these changes. When a match is rejected the suggestion is simply removed and the XJDeveloper project is unaffected.

The confidence score assigned to a match can be made up of up to 4 separate factors which are included or not depending on the data available. The relative weightings of the different factors vary depending on the type of device being matched. Mousing over the score in the Revision Checklist displays a tooltip with a detailed breakdown of all the contributions to the score. See the table below for a brief description of the 4 factors or see Revision Device Matching Algorithm for more detailed information.

Device Match Factor	Description
BOM match	The BOM data for the two devices are compared. Any shared text fields (eg. Description, Part Number) are checked for an exact text match. The Value field, if present on both devices, is checked for a numeric match (eg. 0.1K = 100R).
Pin count match	Check the two devices have the same pin count. For larger devices a margin of 20% is allowed either way to account for unconnected pins that may not be present in the netlist.
Nets match	Each net connected to one device is compared to the same net on the second device. For each net pair, check whether the net names match and check if the net topology (number and type of devices on the net) matches.
Reference designator match	Check the reference designators of the two devices start with the same letter(s) indicating they are the same type of device. If yes, check whether the number matches.