Intel® Time Coordinated Computing Tools (Intel® TCC Tools) 2021.3 Developer Guide

Developer Guide

  • 2021.3
  • 11/18/2021
  • Public
Contents

Troubleshooting

This topic covers general troubleshooting. For tool-specific troubleshooting, see:

Sample Applications

Problem
Possible Cause / Solution
A sample application reports an error.
For more information about the error, enable logging as described in Enable Log Output.

Version

Problem
Possible Cause / Solution
What version of Intel® TCC Tools do I have?
Run the following command to get the version from the binary:
strings /usr/lib64/libtcc.so | grep VERSION
.

Intel® TCC BIOS Error Logging

The Intel® TCC error log is a feature introduced in TCC 2021.3 that allows the BIOS to share error information with the TCC applications.
Accessing the BIOS Error Log
At boot time the BIOS records any errors while applying configurations to the system firmware from the capsules of Cache Configurator and Data Stream Optimizer (DSO) and save the errors to a log. This TCC error log is stored in memory with the pointer and size published in the RTCT ACPI table. To read the TCC error log, get the TCC error log address from the RTCT ACPI table, and then read the specified number of bytes from that physical memory location. These errors are not otherwise displayed during use of TCC.
If TCC drivers are used, you can skip reading the RTCT ACPI table (steps 1 and 2) because the TCC drivers can read the BIOS error log directly. You can go to step 3 (Linux* OS section) directly.
Step 1: Reading RTCT ACPI Table
Linux* OS
BIOS publishes ACPI tables to the OS and the OS manages the tables after firmware load completes and the OS has started. On Linux systems you can read the RTCT ACPI table using the iasl command line tool to decompile the ACPI table to text that you can open with a text editor. The example below uses vim. You can use whatever text editor you are comfortable with.
Linux command line example:
#> cat /sys/firmware/acpi/tables/RTCT > rtct.dat

#> iasl -d rtct.dat

#> vim table.dsl
Step 2: Parsing RTCT ACPI Table to obtain TCC error log address and Size
The RTCT ACPI table contains the standard ACPI header followed by a list of entries for various TCC RTCT entries identified by their entry ID. The user may read the RTCT table binary and find the TCC Error Log entry by scanning the entry IDs for the TCC Error Log ID (0x9) and then reading the TCC Error Log entry to get the address and size of the log.
An example of decoding the table is given below.
Table definitions
Below are the pertinent binary definitions for the RTCT ACPI table.
Header file for these definitions can be found in the BIOS source code path:
Intel\ClientOneSiliconPkg\Include\TccConfigSubregions.h
.
RTCT ACPI table definition
Name
Size in Bytes
Description
EFI_ACPI_DESCRIPTION_HEADER
Sizeof (EFI_ACPI_DESCRIPTION_HEADER)
ACPI table header
RTCT Entries List
Size varies based on type and number of entries
Array of RTCT entries
EFI_ACPI_DESCRIPTION_HEADER
Name
Size in Bytes
Description
Signature
4
Signature of ACPI table
Length
4
Length of ACPI table
Revision
1
Revision number
Checksum
1
Checksum of ACPI table
OemId
6
OEM Identified
OemTableId
8
OEM table ID
OemRevision
4
OEM revision
CreatorId
4
Creator ID
CreatorRevision
4
Creator Revision
RTCT Entries
Name
Size in Bytes
Color
Description
RTCT_HEADER_ENTRY
8
Size of RTCT entry including header
Address
8
Yellow
Physical Memory address of TCC Error Log
Size
4
Cyan
Size of TCC Error Log in bytes
RTCT_HEADER_ENTRY
Name
Size in Bytes
Color
Description
Size
2
Blue
Size of RTCT entry including header
Version
2
Green
RTCT entry version
Type
4
Purple
Type ID of entry
The Entry Type IDs are defined as follows:
RtctCompatibilityType           = 0x00000000

RtctCrlBinaryType               = 0x00000002

RtctIaWayMasksType              = 0x00000003

RtctDdioWayMasksType            = 0x00000004

RtctGtWayMasksType              = 0x00000005

RtctSsramWayMaskType            = 0x00000006

RtctSoftwareSramType            = 0x00000007

RtctMemoryHierarchyLatencyType  = 0x00000008

RtctTccErrorLogAddressType      = 0x00000009
Example
In the example below, colors are marked indicating various fields of RTCT TCC Error Log entry. The address and size in this example are
0x4C7000
 and
0x1E8
 respectively.
Step 3: Reading the TCC Error Log from Memory
The TCC error log is obtained by reading the memory at the address and size indicated in the RTCT TCC Error Log Entry.
Using EFI shell
Shell> mem <address> <size>
Example:
Shell> mem 0x4C7000 0x1E8
Linux OS
~# cat /proc/tcc_errlog
tcc_buffer driver is assumed already loaded once system bootup, as configured by using Intel TCC Tools
The actual error log buffer data displayed is longer than displayed in this screenshot.
Step 4: Interpreting TCC Error Log
The TCC Error Log is composed of:
  1. TCC Error Log Header
  2. An array of DSO errors
  3. An array of TCC Config errors
TCC_ERROR_LOG
Name
Size in Bytes
Description
TCC_ERROR_LOG_HEADER
Sizeof(TCC_ERROR_LOG_HEADER)
Header defined in TCC_ERROR_LOG_HEADER
NumValidDsoErrors
4
Number of valid DSO errors
NumValidTccConfigErrors
4
Number of valid TCC config errors
DsoRegErrors
Sizeof(TCC_REGISTER_ERROR) * MaxDsoErrors
List of DSO related errors. Defined in TCC_REGISTER_ERROR
TccConfigErrors
4 * MaxTccConfigErrors
List of TCC config errors. Each error ID is 4 bytes
NumValidDsoErrors and NumValidTccConfigErrors define the number of valid errors in the table and any error entry beyond that should be ignored
Header
TCC_ERROR_LOG_HEADER
Name
Size in Bytes
Description
Signature
4
Signature of TCC Error Log
Version
4
Version of TCC Error Log
Length
4
Length including header and log
MaxDsoErrors
4
Max number of DSO register errors
MaxTccConfigErrors
4
Max number of TCC Config errors
Max sizes of the arrays are defined in the header as MaxDsoErrors and MaxTccConfigErrors.
DSO errors
The DSO error array (DsoRegErrors) contains a list of registers that failed to be written to during DSO programming. Each register error may be of types MMIO32, MMIO64, MSR, IOSFSB, or Mailbox register, contains the details of what values were being written, and the output of what was read back after writing. If the read back output is different from the expected value, then an error occurred, and a DSO register entry is created
TCC_REGISTER_ERROR
Name
Size in Bytes
Description
RegisterPhase
1
Phase that the error register was programmed
RegisterType
1
Register Type ID: MMIO32 = 0 MMIO64 = 1 MSR = 2 IOSFSB = 3 MAILBOX = 4
RegisterDetail
40
Register details. One of: MMIO32_INFO_ERROR, MMIO64_INFO_ERROR, MSR_INFO_ERROR, IOSFSB_INFO_ERROR, MAILBOX_INFO_ERROR Will always be 40 bytes even if data does not fill entire space
MMIO32_INFO_ERROR
Name
Size in Bytes
Description
Base
4
Base address of register
Address
4
Offset address of register
Mask
4
Data bit-mask
Data
4
Expected data to write
Output
4
Actual data written
MMIO64_INFO_ERROR
Name
Size in Bytes
Description
Base
8
Base address of register
Address
8
Offset address of register
Mask
8
Data bit-mask
Data
8
Expected data to write
Output
8
Actual data written
MSR_INFO_ERROR
Name
Size in Bytes
Description
ApicID
4
APIC ID of processor BIOS attempted to write MSR to
Address
4
MSR offset
Mask
8
Data bit-mask
Data
8
Expected data to write
Output
8
Actual data written
MAILBOX_INFO_ERROR
Name
Size in Bytes
Description
MailboxType
1
Mailbox Register Type
Command
4
Register command address
Mask
4
Data bit-mask
Data
4
Expected data to write
Output
4
Actual data written
Status
4
Mailbox status returned after write
IOSFSB_INFO_ERROR
Name
Size in Bytes
Description
Network
1
IOSFSB Network (i.e. CPU=0, PCH=1)
Port
1
IOSFSB Port ID
IosfSbType
1
IOSFSB Register Type
Address
4
Register Offset
Mask
4
Data bit-mask
Data
4
Expected data to write
Output
4
Actual data written
TCC Config Errors
The TCC config error array (TccConfigErrors) contains a list of TCC Config Error IDs. These error IDs indicate an issue occurred during TCC Config programming
TCC Config Error IDs
TCC Error Name
Error Code
Error Description
Troubleshooting Notes
TCC_ERROR_DSO_TOO_SMALL
0
DSO sub-region size is too small
Try regenerating the DSO tuning configuration binary and update again. If that doesn’t resolve the issue, contact your Intel representative.
TCC_ERROR_CRL_TOO_SMALL
1
CRL sub-region size is zero
Check that capsule update was successful
TCC_ERROR_CRL_TOO_LARGE
2
CRL sub-region uncompressed size is greater than 32KB
Contact your Intel representative
TCC_ERROR_CACHE_CONFIG_TOO_SMALL
3
Cache Config sub-region size is too small
Try regenerating cache configuration binary and update again. If that doesn’t resolve the issue, contact your Intel representative.
TCC_ERROR_DSO_NOT_FOUND
4
DSO sub-region is not found or failed to authenticate
Check that the DSO capsule update was successful. Ensure signing was done with the correct key hashes and the corresponding public keys are store in the system firmware
TCC_ERROR_CRL_NOT_FOUND
5
CRL sub-region is not found or failed to authenticate
Check that the CRL capsule update was successful. Ensure signing was done with the correct keys and the corresponding public keys are store in the system firmware
TCC_ERROR_CACHE_CONFIG_NOT_FOUND
6
Cache Config sub-region is not found or failed to authenticate
Check that the Cache Config capsule update was successful. Ensure signing was done with the correct keys and the corresponding public keys are store in the system firmware
TCC_ERROR_DSO_VERSION
7
DSO sub-region version is not supported
Contact Intel representative
TCC_ERROR_CACHE_CONFIG_VERSION
8
Cache Config sub-region version is not supported
Contact Intel representative
TCC_ERROR_CACHE_CONFIG_WRC_WRITE
9
Cache Config sub-region Intel® Data Direct I/O Technology (Intel® DDIO) waymask failed to write. e.g. Selected ways in waymask are not continuous, no ways are selected, or the number of selected ways is greater than the max supported ways
Check that Intel® DDIO waymask in cache configuration is a valid value
TCC_ERROR_CACHE_CONFIG_GT_COS_WRITE
10
Cache config sub-region GT class of service (COS) waymask failed to write. e.g. Selected ways in waymask are not continuous, no ways are selected, or the number of selected ways is greater than the max supported ways
Check that GT COS waymask in cache configuration is a valid value
TCC_ERROR_CACHE_CONFIG_IA_L2_COS_WRITE
11
Cache Config subregion L2 class of service (COS) waymask failed to write. e.g. Selected ways in waymask are not continuous, no ways are selected, or the number of selected ways is greater than the max supported ways
Check that L2 COS waymask in cache configuration is a valid value
TCC_ERROR_CACHE_CONFIG_IA_L3_COS_WRITE
12
Cache Config subregion L3 class of service (COS) waymask failed to write. e.g. Selected ways in waymask are not continuous, no ways are selected, or the number of selected ways is greater than the max supported ways
Check that Intel® DDIO waymask in cache configuration is a valid value
TCC_ERROR_CACHE_CONFIG_SSRAM_ALLOCATE
13
Failed to allocate SSRAM. e.g. total L2 SSRAM does not fit in L3 SSRAM
Check SSRAM values in SSRAM allocation. All L2 SSRAM allocation should fit inside the L3 SSRAM allocation
TCC_ERROR_DSO_WATCHDOG_TIMEOUT
14
Failed to apply DSO stream tuning configuration. System booted without applying DSO stream tuning
Regenerate DSO tuning configuration and apply again. Otherwise contact Intel representative

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.