Inter-Integrated Circuit (I2C) Test (Compact 7)
3/12/2014
The Inter-Integrated Circuit (I2C) module provides the functionality of a standard I2C subordinate and master. I2C driver tests the I2C module by performing read/write transactions between a I2C subordinate device and the test thread which acts as the I2C master.
I2C Driver is a stream interface driver and exposes basic stream APIs such as Read, Write, IOControl. I2C SDK APIs are the wrapper functions over these stream APIs. I2C driver test uses these SDK APIs to interact with I2C.
The I2C transaction details such as I2C master name, subordinate address, register address, speed of transaction, etc are specified in a XML configuration file. Since I2C test needs to be run in kernel mode, this XML file cannot be accessed and parsed in the same test DLL. So a separate program I2CConfigParser.exe is used to parse this XML config file which runs in user mode. The data retrieved by this user mode program is then transferred to the test DLL which runs in kernel mode.
NOTE:
This test is only applicable to I2C drivers that use the common I2C MDD APIs.
Test Prerequisites
Your device must meet the following requirements before you run this test.
* The I2C Driver Test requires that the Windows Embedded Compact-based device be equipped with I2C bus and at least one I2C subordinate device:
The following table shows the SYSGEN and BSP variables to be set in the Windows Embedded Compact-based device image for the I2C Test.
| Requirements | Description |
|---|---|
BSP_I2CBUS1 |
To include I2C bus driver |
BSP_CAMERA |
To include I2C subordinate device Camera driver |
IMGCEPERF |
To include CEPerf.dll in the image for performance testing |
The following table shows the software requirements for the I2C Test.
| Requirements | Description |
|---|---|
Tux.exe |
Tux Test Harness, required for executing the test |
Kato.dll |
Kato logging engine, required for logging test data |
KTux.dll |
Kernel mode Tux |
TestI2C.dll |
Library containing the test |
I2CConfigParser.exe |
Config File parser tool |
I2C Test Configuration XML |
The XML config file containing the I2C transaction details |
PerfScenario.dll |
Performance Library for the performance test |
CePerf.dll |
CEPerf Library for the performance test cases |
* I2C Test Configuration XML:
The test uses a configuration file to get the i2c data specific to a platform. Please edit the config file to use I2C transaction details specific to the platform under test. User can specify the config file through command line parameters.
The input configuration file has a list of transaction nodes that are used for testing the bus. A valid transaction node contains the mandatory fields as shown below:
<Transaction ID="<Transaction ID>">
<BusName>[Bus name e.g I2C1:]</BusName>
<SubordinateAddress>[subordinate address e.g 0x30]</SubordinateAddress>
<Operation>[operation: write /read/loopback]</Operation>
<Data>[data: space separated hex bytes]</Data>
<RegisterAddress>[register address e.g 0x01]</RegisterAddress>
<NumberOfBytes>[number of bytes to read/write]</NumberOfBytes>
</Transaction>
Additionally a valid transaction may also have following optional fields:
<SubordinateAdressSize>[size of subordinate address]</SubordinateAdressSize>
<RegisterAdressSize>[size of register address]</RegisterAdressSize>
<Speed>[speed of transaction]</Speed>
<TimeOut>[timeout for a single transaction]</TimeOut>
* I2C TestHook
Some I2C registers have to be enabled before I2C module is available for any Read/Write operation by any master device. This is done with the help of I2C Test Hook which enables the I2C Read/Write register just before the test starts and then disables it back after the test is over. For iMX27, the test hook is iMX27I2CTestHook.dll
Subtests
This test has no subtests.
Setting Up the Test
The test uses a Test configuration file to get the i2c data specific to a platform. Before running the test, the I2C Test Configuration XML has to be edited as per the platform on which test is going to be performed. User can specify the config file through command line parameters. However this is optional. The default name of the configuration file is I2C_Test_Config.xml
The input configuration file has a list of transaction nodes that are used for testing the bus. A valid transaction node contains the mandatory fields as shown below:
<Transaction ID="<Transaction ID>">
<BusName> [Bus name e.g I2C1:] </BusName>
<SubordinateAddress> [subordinate address e.g 0x30] </SubordinateAddress>
<Operation> [operation: write /read/loopback] </Operation>
<Data> [data: space separated hex bytes] </Data>
<RegisterAddress> [register address e.g 0x01] </RegisterAddress>
<NumberOfBytes> [number of bytes to read/write] </NumberOfBytes>
</Transaction>
Additionally a valid transaction may also have following optional fields:
<SubordinateAdressSize> [size of subordinate address] </SubordinateAdressSize>
<RegisterAdressSize> [size of register address] </RegisterAdressSize>
<Speed> [speed of transaction] </Speed>
<TimeOut> [timeout for a single transaction] </TimeOut>
I2C Test Hook
I2C Test hook is used to perform any operations on the I2C Driver before executing the actual test. For example, in some platforms I2C registers are disabled by default and could not be used for read/write operations. To enable these registers, a special I2C register has to be set. This can be achieved with the help of a test hook which will run just before the test starts and enable the registers. The registers can be disabled back at the end of test by the same test hook.
I2C Test Hook is a DLL with following 2 functions -
| Function | Description |
|---|---|
BOOL I2CTestHookInit() |
This function is called just before the test suite starts. Any operations which needs to be performed before the start of the test should be put inside this function. |
BOOL I2CTestHookDeInit() |
This function is called just after the test suite completes. Any operations required for reverting the changes done at the start of the test should be put inside this function |
Running the Test
The I2C Driver Test executes the tux -o -n -d testi2C command line on default execution
The following table shows the optional command line parameters for the I2C DriverTest.
| Command line parameter | Description |
|---|---|
/time |
Specifies the stress test time duration in minutes. Optional parameter. The default value is 10 mins. |
/config |
Specifies the complete path of Transaction XML configuration file. Optional parameter. The default value is \Release\I2C_Test_Config.xml |
/testhook |
Specifies the I2C Test Hook Dll which needs to be executed before performing the actual test operations on the I2C Driver. This test hook needs to be developed by the tester/developer specific to a platform |
Example: tux -o -n -d testi2c -c"/time 15 /config i2c_Test_config.xml" -x!3000,3001
Verifying the Test
This test reports a Pass or Fail result.
Troubleshooting the Test
1. If all test cases are failing because of unable to read/write on the device, please ensure that the correct subordinate device address and register address are specified in the I2C Test Configuration XML
2. If the device address and the subordinate address are correct in the Test Configuration XML and still all the test fails due to read/write operation failure, check if the I2C registers are enabled for read/write. In some devices, I2C registers are disabled by default and needs to be enabled before any read/write operation could be performed on them. This can be achieved through I2C Test Hook. For more details on Test Hook, please refer the section 'Setting up the Test'
For additional platform specific issues, consult the CTK articles on the TechNet wiki.