IP‑XACT Document Checker

The IP‑XACT editor is able to check documents against a fixed set of rules.  These rules are separate from, and in addition to, those enforced by the XML schema validation mechanism.  The Document Checker rules encompass many of the IP‑XACT Semantic Rules described in the IP‑XACT User Guide.

To run the Document Checker, select the file to be checked in the IP‑XACT Library view, then select Check document from the context menu or the toolbar.

When the document is being checked, it is first opened in the editor (if it’s not already open), and then markers are placed around the document Source window indicating where any rule check notifications have been made.

The strip on the right shows the location of all the markers in the document.  Individual markers appear in the left-hand margin, which, if you hover over them with the mouse, show a short summary of the check’s notification.

The Document Checker notifications also appear in the Problems view.  You can use the Go To item in the context menu of the Problems view to jump to the relevant point in the document.

Note: The Document Checker relies on the XML being checked being valid with respect to the IP‑XACT schema.  Before executing any checks, the Document Checker ensures that the XML within the editor is valid.  If it is not valid, further checking is aborted and the following problem is listed:

If this is the case, switch to the Source tab of the editor and examine the right-hand margin.  The type and location of the schema errors will be apparent when you hover over the colored markers.  These errors will need to be corrected before rechecking the document.

*  Tip: You can also run the Document Checker from the context menu of the Source editor.

*  Tip: In addition, you may select Clear Check Markers from the context menu of the Source editor to remove any notifications that the Document Checker created.

Document Checker Rules

The Document Checker implements a fixed set of rules that are appropriate for the type of document being checked.  The majority of the rules are those defined by the Spirit Consortium’s IP-XACT™ User Guide v1.2.  (This is available for download – see The SPIRIT Consortium’s Public Release Documentation.)  The table below lists those rule numbers that have been implemented.

 

Rule Numbers

Section[1]

1 - 11

6.1          Cross references and VLNVs

12 - 24

6.2          Interconnections

25 - 30

6.3          Channels and bridges

31 - 36

6.4          Monitor interfaces and interconnections

No rules will be implemented

6.5          Configurable elements

49

6.6          Signals

50 - 53

6.7          Registers

54 - 56

6.8          Memory maps

57 - 58

6.9          Addressing.

59 – 71

6.10        Hierarchy

Not implemented

6.11        Hierarchy and memory maps.

76

6.12        Rules requiring external knowledge

No rules will be implemented

6.13        PMD files

 

Furthermore, the Document Checker employs a small number of additional rules (numbered from 1000) that are not a part of the above specification.  These additional rules give information or warnings, but not errors.

Document Checker Configuration

The IP‑XACT XML element spirit:file/spirit:name is used to reference a file or directory.  Furthermore, these elements may contain file path variables in the format ${VAR}.  These variables are useful in the case where you want to reference files in a host-independent way.

The Document Checker verifies that the files referenced by spirit:file/spirit:name elements are present.  There are, however, two configuration options for the Document Checker that make this possible: first, you can supply “File Path Variables” to the Document Checker; and second, you may supply “File Path Roots”.  Both of these configuration options are accessed through the Document Checker Preferences.

To display the Document Checker preferences, first select Window – Preferences… to display the Preferences dialog.  Locate the IP‑XACT node in the tree and expand it to reveal the Document Checker node.  Select the Document Checker node to display the Document Checker’s Preferences.

Describing how the Document Checker may be used to validate IP‑XACT spirit:file/spirit:name elements is perhaps best illustrated by example.

First create a new IP‑XACT component file in the Example project you created earlier.  (See the section Create a new IP‑XACT File for details about how to do this, but select component rather than busDefintion.).  Call the file component.spirit.

Select the Source editor tab for the new component.spirit file, and just before the closing </spirit:component> element, insert the following:

  <spirit:fileSets>

    <spirit:fileSet spirit:fileSetId="fileSet1">

      <spirit:file>

        <spirit:name>test.txt</spirit:name>

        <spirit:fileType>unknown</spirit:fileType>

      </spirit:file>

    </spirit:fileSet>

  </spirit:fileSets>

 

Now save this file and run the Document Checker on it.  Observe that a checker report is generated in the Problems view:

File resource not found: test.txt (ignore any other reports).

Now create a text file called test.txt.  (Select the Example project in the Navigator, and then select File – New – Other…  In the New dialog, expand General node, select File and then select Next.  Enter the File name: test.txt and select Finish.

Re-select component.spirit in the editor and re-run the Document Checker.  Observe that the checker report for test.txt is no longer given.

This example illustrates that the Document Checker supports relative file references.  (For example, you may change <spirit:name>test.txt</spirit:name> to <spirit:name>./test.txt</spirit:name> and observe that still no checker report is generated for this file.)

*  Tip: Microsoft Windows™ users are recommended to use forward slashes (/) for file paths in spirit:file/spirit:name elements.

Delete the test.txt file before continuing with this demonstration.  (Right-click on test.txt and select Delete in the context menu.  Select Yes to confirm the deletion.)

Using File Path Variables

Edit the <spirit:name>test.txt</spirit:name> element created above to read: <spirit:name>${TEST}/test.txt</spirit:name>.

Now when you run the Document Checker you will receive these two reports in the Problems view (ignore any other reports):

File resource not found: ${TEST}/test.txt
Unresolved variable: TEST

Using a text editor, create a file in your home directory called test.txt.  Now open the Document Checker Preferences (see Document Checker Configuration) and next to the File Path Variables table, select the New… button.  The New File Path Variable dialog appears.

In the Variable field, enter TEST.

In the Value field, enter the full directory path to where you created the test.txt file, and select OK.

The new variable should appear in the File Path Variables table.

Select OK to close the Preferences dialog.

Now re-run the Document Checker on the component.spirit document and observe that the two reports for test.txt and TEST are no longer generated.

*  Tip: A variable’s value, may reference another variable.  For example, you may set the TEST variable’s value to ${HOME}/Work where a variable already exists for HOME.

Using Environment Variables

If you check the box Treat System Environment Variables as File Path Variables under the Document Checker’s Preferences, then the operating system’s environment variables that are set for the current user before the Eclipse session was started will be treated as File Path Variables.

For example, on a Microsoft Windows™ system, you may set the TEST File Path Variable to something like ${HOMEDRIVE}\${HOMEPATH}\My Documents, since HOMEDRIVE and HOMEPATH are environment variables set by Microsoft Windows™.

If you try this and receive the reports

Unresolved variable: HOMEDRIVE
Unresolved variable: HOMEPATH

when checking a file, then it is likely that the Treat System Environment Variables as File Path Variables box is not checked.

Using File Path Roots

You can use the Document Checker’s File Path Roots feature to locate common files even though they do not have a File Path Variable and are not adjacent to the checked document.

Edit the <spirit:name>${TEST}test.txt</spirit:name> element created above to read: <spirit:name>test.txt</spirit:name>.  (If you check the document now, you will get a File resource not found: test.txt report.)

Now display the Document Checker Preferences again, and select the New… button adjacent to the File Path Roots table.  The Browse For Folder dialog appears:

In this dialog, select the directory containing the test.txt file, then select OK.

Now if you re-check the document, you will find that the report for test.txt is no longer generated.

*  Tip: Paths in spirit:file/spirit:name elements may be relative (for example: ../vhdlSource/busDef.vhd), but can still be fully resolved when combined with a File Path Root.

*  Tip: Paths in spirit:file/spirit:name elements may contain file path variables, but can still be fully resolved when combined with a File Path Root.

 



[1] See the Spirit Consortium’s IP-XACT™ User Guide v1.2.