Summary

Catalog Service is a new functionality in Intel(R) System Trace, which is going to deprecate existing trace extension support. When your Intel(R) System Trace runs, it automatically detects firmware versions, trying to match correct catalog files.

Currently the Catalog service is supported in TraceCLI and Eclipse GUI.

The Catalog service can:

• Import and automatically detect catalogs from trace extension and xml files,

• Keep multiple versions of catalogs at once, in organized local repository,

• Automatically find and download missing catalog files from remote repositories (if configured).

For use with the Catalog Service a new entity was implemented named Version Context:

• Version Context gives information about type and version of component captured during trace recording

• Examples of Version context: BIOS / 10.20.30; ACE / 20.30.10

• Version Context data can be pulled automatically from the target via TCA Hotham functionality or provided manually.

Catalog Service working directory

Catalog service accumulates imported catalogs in a sorted manner into working directory.

Working directory location is depending of the OS, on Windows it’s by default:

C:\Users\[USER]\AppData\Local\Intel\intel-system-trace\catalog

On Linux it’s:

/home/[USER]/.intel/intel-system-trace/catalog/

Inside working directory index.txt file is created with list of all indexed files, tightly connected to file structure under “content” directory.

Importing files and directories into Catalog Service

To import a single file use command:

intel_systrace catalog --import path/to/file.traceext

You can also import a whole directory:

intel_systrace catalog --import directory_path

Or import the directory recursively:

intel_systrace catalog --import directory_path -r

After import a summary will be generated containing:

• List of recognized and successfully imported catalog files, if any

• List of recognized catalogs which are already imported into working directory, if any

• List of unrecognized catalogs which could not be imported (with information what was not recognized)

If your trace extension or xml catalog file was not recognized at all, it’s either invalid or not yet supported.

If some part (kind/platform/version) is not detected you can specify it manually (every –def parameter is optional):

intel_systrace catalog --import path/to/file.traceext --def-kind ace --def-platform mtl --def-version 1.2.3.4

Specifying parts is only possible when importing a single file, for directories this functionality is disabled for security reasons.

Structure of catalog index

Catalogs are categorized by 3 main features:

• Component (root element) - IP for which symbols are dedicated, for example cse, ace, bios…

• Platform - name of platform containing IP for which symbols are dedicated, for example mtl, lnl…

• “all” platform is available as special case for catalogs applicable for every platform.

• Version - describing version of IP. Version can contain tags (more in Version query format paragraph)

There are catalog attributes which are stored in the index as well:

• Type - describing catalog type: can be SyS-T, SBD, SVEN, DecoderData file.

• Compression - telling if stored catalog is compressed or not.

The index.txt file located in the Catalog Service working directory contains all stored symbols which can be used by the Catalog Service.

Version query format

Version of catalog indexed on server consist two parts:

• Actual version string, for example 1001.480247808

• Optional tags, with tag name and optional tag value

In this sample version string is 19.0.0.7317, with additional tag: build_​id with value of 15238151:

19.0.0.7317#build_id=15238151

In this sample version is 10.20.30 with optional tags: internal and A0. Tags don’t have any assigned value, but search can be performed just by their presence:

10.20.30#internal#A0

When asking the Catalog Service for catalogs, the user can specify a version query which is very similar to the version representation of catalogs in index.

Search query structure

To search for versions, user can specify query in the following format:

[GLOB expression matching version string][Optional tags[=optional values]]

For example:

• “19.0.0.7317” will match “19.0.0.7317” but also “19.0.0.7317#build_​id=1” and “19.0.0.7317#build_​id=2”.

• “19.0.0.?” will match any version beginning at “19.0.0.” regardless of tags.

• “19.0.0.?#internal” will match any version beginning at 19.0.0. which has “internal” tag defined.

• “*#build_​id” will match any version which has build_​id defined.

• “*#build_​id=123123” will match any version with build_​id equal to 123123.

Generally, for decoding scenario, the user should specify version query that is addressing exactly one concrete version of catalogs for one component. When multiple versions are matched, decoding conflicts may occur.

Getting Version Context from TCA device info (Hotham)

Loading Version Context from TCA is performed automatically by TraceCLI, either during loading of the trace capture file, or just before starting capturing/streaming.

For .tracecpt (Trace capture) archives, catalog service is looking for config/tca-device-info.json file.

If found, the following sections are used (as in example):

"firmware_info": {
   "CPU_FAMILY_ID": "MTP",
   "CSE_FW_VER": "19.0.0.1490",
   "CSE_SKU_ID": "CORP",
   "CSE_STATE_ID": "NORM",
   "ESEPP_FW_VER": "1001.0.0.1503",
   "ESE_FW_VER": "1100.0.0.1499",
   "PCH_FAMILY_ID": "MTP",
   "PCH_SKU_ID": "S",
   "SYSTEM_STATE_ID": "S0"
},
"trace_info": {
   "CSE_CATALOG_ID": "0x11bb53"
}

Every entry matching X_​FW_​VER will map to version context with component name defined as X, and version value equal JSON entry value. In this example, ESEPP component gets version “1001.480247808”.

In streaming scenario, the same TCA device info is used, by querying the information directly from the connected target.

Providing Version Context data from command line

If TCA device info is missing, invalid or doesn’t contain the component which the user wants to decode, a manual component version can be provided from command-line. Component versions can be provided to decode and capture commands.

intel_systrace decode example.tracecpt --component ace 20.00.00.1180 --component sse_pch 10.20.30

In this example we’re decoding example.tracecpt file with 2 extra defined components: ACE with version 20.00.00.1180 and SSE_​PCH with version 10.20.30. User-specified versions have priority over the autodetected versions.

Providing Catalog File or Directory Instead of Version Info

When working with Intel System Trace, there may be instances where you need to apply a specific catalog file or directory to a component, bypassing the automatic version detection and matching. This can be achieved by using the –component-catalog parameter:

intel_systrace decode example.tracecpt --component-catalog ace c:\path\to\catalog.xml

Trace extension files are also supported:

intel_systrace decode example.tracecpt --component-catalog ace c:\path\to\catalog.traceext

As well as full directories, which will be scanned for catalog files, not recursively:

intel_systrace decode example.tracecpt --component-catalog ace c:\path\to\catalog\dir\

In a need of just including particular catalog into decoding process, without specifying component –catalog parameter can be used:

intel_systrace decode example.tracecpt --catalog c:\path\to\catalog.traceext

intel_systrace decode example.tracecpt --catalog c:\path\to\catalog\dir\

Version context json file - import and export

In TraceCLI version context json file can be imported and exported during decode or capture.

To export components detected during decode (and optionally specified by user) use the –export-components argument:

intel_systrace decode example.tracecpt --export-components components.json

You can combine commands to specify components which will be appended to file:

intel_systrace decode example.tracecpt --component ace 20.00.00.1180 --export-components components.json

In this case, the output file will contain the components detected inside the example.tracecpt file as well as the user-specified “ace” component with version 20.00.00.1180.

Previously exported components can be imported for the next decoding using –import-components argument:

intel_systrace decode example.tracecpt --import-components components.json

Example structure of the components JSON file:

[
   {
   "kind": "ace",
   "version": "20.00.00.1180",
   "locked": true
   },
   {
   "kind": "cse",
   "version": "19.0.0.7317#build_id=15238151",
   "locked": false
   },
   {
   "kind": "esepp",
   "version": "1001.480247808",
   "locked": false
   },
   {
   "kind": "sse_pch",
   "version": "1100.480378880",
   "locked": false
   }
]

Locked flag: It’s important to notice, that version info for one component can (and will be) overridden by TCA device info if it’s available. To avoid this, the user can enforce their entry by changing the “locked” flag to true. By default, all data provided by user using command-line arguments is locked.

Remote catalog repository support

The Catalog Service can connect to a remote repository to search and download missing catalogs. Currently two types of repositories are supported:

• Local filesystem or network share mapped in local filesystem.

• JFrog/Artifactory.

The Catalog Service implementation in TraceCLI will automatically try to download missing catalogs. Once downloaded, the catalogs will stay in local storage, such as catalogs manually imported by user. The List of remote repositories is located in Catalog Service configuration file.

Defining Catalog Service configuration

By default, Catalog Service comes with no configuration. Creating the configuration is not strictly required, unless you want to add remote repositories. You can create the configuration manually or use the configuration utility.

C:\Users\[USER]\AppData\Local\Intel\intel-system-trace\catalog\config.json

/home/[USER]/.intel/intel-system-trace/catalog/config.json

{
   "compression": {
      "type": "gzip"
   },
   "remotes": [
      {
      "name": "Local filesystem or network remote",
      "type": "native_raw_fs",
      "address": "E:/Remote/Catalog/"
      }
   ]
}

intel_systrace catalog-config remote-list

intel_systrace catalog-config remote-set "Name" directory "E:/Remote/Catalog"

intel_systrace catalog-config remote-set "Name" artifactory https://url.to.remote/ --token PUT_TOKEN_HERE

intel_systrace catalog-config remote-remove "Name"